Change:
/// assert_eq!(b"Rust", &[82, 117, 115, 116]); /// ``` /// <del> /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`: </del> <ins> /// Turning a `Vec<&T>` into a `Vec<Option<&T>>`. /// /// To transmute the inner type of the contents of a container, you must make sure to not /// violate any of the container's invariants. For `Vec`, this means that both the size /// *and alignment* of the inner types have to match. Other containers might rely on the /// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't /// be possible at all without violating the container invariants. </ins> /// /// ``` /// let store = [0, 1, 2, 3];

Discussion:
The documentation for  reads: However, it does not mention that they must also have the same alignment. You would only learn about this if you try to dig into the code examples further down the page: Must the types and have the same alignment, or is that a particular quirk of the example? In any case, I think the documentation should explicitly mention alignment, because the compiler succeeds to compile the following with no warnings (), and I believe this is undefined behaviour: modify labels: +T-doc +C-enhancement
That looks like well-defined behavior to me. The alignment of is a relevant property if a transmute produces a reference to but for values it is the compiler's job to make them addressable at a properly aligned stack location (it doesn't strictly have to if no one takes a pointer to it). Regarding the quote paragraph, this references a conversion of to . The presented method does in fact cast pointers, but pointers to the value types inside the vector: to . It is the Vec which requires the pointee types to have the exact same size and alignment as a precondition for —and not transmutation.
Thanks for the clarification! So the documentation could still be updated to clarify when alignment matters, right?
I do not see a feasible way for the documentation to explain for all possible types which guarantees matter. Alignment is just one of many examples. Whether you can transmute to depends on the details of (and, less so, ), and I don't think can cover this for all possible . You example (the text you quoted) is specific to , and here it is alignment that matters. Another time, you might to ; this is also UB but this time alignment has nothing to do with it. And the list goes on forever.
However, maybe the comment in the example could be worded a bit more carefully to explain that alignment matters in this specific case because we are transmuting a pointer (implicitly as part of the ). Do you have any suggestions for how that could be worded? Honestly, that entire example is a bit weird. It says "still using transmute" but the code this comments doesn't even use .
If alignment is not a concern when transmuting values (because the compiler will move the memory to a stack location which is properly aligned), I think it would be worth explicitly saying this.

Unless I was explicitly told (like Heroic explained), it would not have occured to me that it's moving into a proper aligned location. With regards to "explain all possible types", I don't think this is necessary. Saying "The resulting type must be a valid value" might be enough. Or maybe the: …should be changed to encourage reading that page more strongly ("Make sure you understand all the dangers of using before using it"), because that page does mention the invalid values thing (but it doesn't mention alignment at all, which is what raised this issue). It's not even use directly, it's casting pointers (which, sure, can be seen as a different way of transmuting values), where different rules apply. Maybe the example could be completely removed or moved elsewhere. Or framed differently, something like:
I'm not a fan of listing all the things that are not a concern. That's a long list. However, you are not the first person to suggest this, so I concede. I guess I will never understand why people expect alignment to be an issue here, but it seems they do, and I don't have to understand everything. ;) It already says that (in double-negated form): "Neither the original, nor the result, may be an invalid value." There are people (myself included) that use the term "to transmute" for any kind of "type-changing reinterpretation of raw bytes", whether it is via , via a pointer cast, or via union field accesses. The rules are the same in each case. However, since this is the docs of the function specifically, I think we should be more precise here, and I like your new framing.
In my case, it's because I'm not sure if it was undefined behaviour to read a type from memory with the wrong alignment. IIRC, there are some CPU architectures that fault when a misaligned memory access occurs? Or maybe I'm misremembering. Basically, I wasn't sure if "interpret this bunch of bytes as this other type" is something that is okay to do when "the bunch of bytes" is misaligned. My bad, somehow missed it.
It is UB to perform an unaligned read or write. But is a by-value operation, so you anyway have no control over the location at which or end up.

Anyway, you made some good suggestions -- do you plan to turn these into a PR, or should we mark this as an E-easy issue for someone else to write the PR?