Rollup merge of #99614 - RalfJung:transmute-is-not-memcpy, r=thomcc

do not claim that transmute is like memcpy

Saying transmute is like memcpy is not a well-formed statement, since memcpy is by-ref whereas transmute is by-val. The by-val nature of transmute inherently means that padding is lost along the way. (This is not specific to transmute, this is how all by-value operations work.) So adjust the docs to clarify this aspect.

Cc `@workingjubilee`

library/core/src/intrinsics.rs

@@ -1207,29 +1207,34 @@ extern "rust-intrinsic" {
 
  /// Reinterprets the bits of a value of one type as another type.
  ///
- /// Both types must have the same size. Neither the original, nor the result,
- /// may be an [invalid value](../../nomicon/what-unsafe-does.html).
+ /// Both types must have the same size. Compilation will fail if this is not guaranteed.
  ///
  /// `transmute` is semantically equivalent to a bitwise move of one type
  /// into another. It copies the bits from the source value into the
- /// destination value, then forgets the original. It's equivalent to C's
- /// `memcpy` under the hood, just like `transmute_copy`.
+ /// destination value, then forgets the original. Note that source and destination
+ /// are passed by-value, which means if `T` or `U` contain padding, that padding
+ /// is *not* guaranteed to be preserved by `transmute`.
+ ///
+ /// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at
+ /// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler
+ /// will generate code *assuming that you, the programmer, ensure that there will never be
+ /// undefined behavior*. It is therefore your responsibility to guarantee that every value
+ /// passed to `transmute` is valid at both types `T` and `U`. Failing to uphold this condition
+ /// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly
+ /// unsafe**. `transmute` should be the absolute last resort.
+ ///
+ /// Transmuting pointers to integers in a `const` context is [undefined behavior][ub].
+ /// Any attempt to use the resulting value for integer operations will abort const-evaluation.
+ /// (And even outside `const`, such transmutation is touching on many unspecified aspects of the
+ /// Rust memory model and should be avoided. See below for alternatives.)
  ///
  /// Because `transmute` is a by-value operation, alignment of the *transmuted values
  /// themselves* is not a concern. As with any other function, the compiler already ensures
  /// both `T` and `U` are properly aligned. However, when transmuting values that *point
  /// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper
  /// alignment of the pointed-to values.
  ///
- /// `transmute` is **incredibly** unsafe. There are a vast number of ways to
- /// cause [undefined behavior][ub] with this function. `transmute` should be
- /// the absolute last resort.
- ///
- /// Transmuting pointers to integers in a `const` context is [undefined behavior][ub].
- /// Any attempt to use the resulting value for integer operations will abort const-evaluation.
- ///
- /// The [nomicon](../../nomicon/transmutes.html) has additional
- /// documentation.
+ /// The [nomicon](../../nomicon/transmutes.html) has additional documentation.
  ///
  /// [ub]: ../../reference/behavior-considered-undefined.html
  ///