Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

mem::transmute() docs could use some additional detail #44281

Closed
wesleywiser opened this issue Sep 3, 2017 · 1 comment
Closed

mem::transmute() docs could use some additional detail #44281

wesleywiser opened this issue Sep 3, 2017 · 1 comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. E-hard Call for participation: Hard difficulty. Experience needed to fix: A lot. P-medium Medium priority

Comments

@wesleywiser
Copy link
Member

wesleywiser commented Sep 3, 2017

Here's a few things I thought of while reading the docs:

  • The term type punning is used without being defined. Ordinarily, I wouldn't complain about this because it's very easy to Google search but most of the search results on the first page say that type punning is undefined behavior (in C\C++). This doesn't appear to be true in Rust because the Undefined Behaviors Page only references LLVM's pointer aliasing rules which seem to indicate that TBAA doesn't apply.
    • It would probably be a good idea to give a short definition of the term and state that it is (or is not) undefined behavior in Rust.
~~~  - Having an explicit reason stated as to why it's UB would help the reader figure out if the same rule applies to what they are trying to do.~~~

- Another common use of type punning in C is to take a set of bytes (perhaps read off disk or the network) and then cast them into a `struct` of the same size. 
  - I think this is an allowed usage of `transmute()` provided the struct is `repr(C)`. Having an example that shows how to do this correctly and also discusses the potential issues such as relying on the endianness being the same would be helpful. If this isn't allowed, then stating that would also be useful.
@sfackler sfackler added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Sep 3, 2017
@alexcrichton alexcrichton added the C-enhancement Category: An issue proposing an enhancement or a PR with one. label Sep 7, 2017
GuillaumeGomez added a commit to GuillaumeGomez/rust that referenced this issue Sep 13, 2017
Fix example in transmute; add safety requirement to Vec::from_raw_parts

This fixes the second bullet point on rust-lang#44281 and also removes some incorrect information.
frewsxcv added a commit to frewsxcv/rust that referenced this issue Sep 14, 2017
Fix example in transmute; add safety requirement to Vec::from_raw_parts

This fixes the second bullet point on rust-lang#44281 and also removes some incorrect information.
frewsxcv added a commit to frewsxcv/rust that referenced this issue Sep 15, 2017
Fix example in transmute; add safety requirement to Vec::from_raw_parts

This fixes the second bullet point on rust-lang#44281 and also removes some incorrect information.
@steveklabnik steveklabnik added the P-medium Medium priority label Oct 31, 2017
@steveklabnik steveklabnik added the E-hard Call for participation: Hard difficulty. Experience needed to fix: A lot. label May 29, 2018
@Mark-Simulacrum
Copy link
Member

We no longer mention type punning and there appears to be pretty extensive documentation around transmute (both on the main docs, in the nomicon, and the reference), all of which are linked from transmute. As such, closing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools C-enhancement Category: An issue proposing an enhancement or a PR with one. E-hard Call for participation: Hard difficulty. Experience needed to fix: A lot. P-medium Medium priority
Projects
None yet
Development

No branches or pull requests

5 participants