Skip to content

Commit

Permalink
Use pseudocode to document transmute, transmute_mut
Browse files Browse the repository at this point in the history
Partially addresses #1046.
  • Loading branch information
jswrenn committed Mar 19, 2024
1 parent 9fe8aae commit 423beb7
Showing 1 changed file with 43 additions and 13 deletions.
56 changes: 43 additions & 13 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4347,14 +4347,30 @@ mod simd {
/// Safely transmutes a value of one type to a value of another type of the same
/// size.
///
/// The expression `$e` must have a concrete type, `T`, which implements
/// `IntoBytes`. The `transmute!` expression must also have a concrete type, `U`
/// (`U` is inferred from the calling context), and `U` must implement
/// `FromBytes`.
/// This macro behaves like an invocation of this function:
///
/// Note that the `T` produced by the expression `$e` will *not* be dropped.
/// Semantically, its bits will be copied into a new value of type `U`, the
/// original `T` will be forgotten, and the value of type `U` will be returned.
/// ```ignore
/// const fn transmute<Src, Dst>(src: Src) -> Dst
/// where
/// Src: IntoBytes,
/// Dst: FromBytes,
/// size_of::<Src>() == size_of::<Dst>(),
/// {
/// # /*
/// ...
/// # */
/// }
/// ```
///
/// However, unlike a function, this macro can only be invoked when the types of
/// `Src` and `Dst` are completely concrete. The types `Src` and `Dst` are
/// inferred from the calling context; they cannot be explicitly specified in
/// the macro invocation.
///
/// Note that the `Src` produced by the expression `$e` will *not* be dropped.
/// Semantically, its bits will be copied into a new value of type `Dst`, the
/// original `Src` will be forgotten, and the value of type `Dst` will be
/// returned.
///
/// # Examples
///
Expand Down Expand Up @@ -4562,13 +4578,27 @@ macro_rules! transmute_ref {
/// Safely transmutes a mutable reference of one type to a mutable reference of
/// another type of the same size.
///
/// The expression `$e` must have a concrete type, `&mut T`, where `T: Sized +
/// IntoBytes`. The `transmute_mut!` expression must also have a concrete type,
/// `&mut U` (`U` is inferred from the calling context), where `U: Sized +
/// FromBytes`. It must be the case that `align_of::<T>() >= align_of::<U>()`.
/// This macro behaves like an invocation of this function:
///
/// The lifetime of the input type, `&mut T`, must be the same as or outlive the
/// lifetime of the output type, `&mut U`.
/// ```ignore
/// const fn transmute_mut<'src, 'dst, Src, Dst>(src: &'src mut Src) -> &'dst mut Dst
/// where
/// 'src: 'dst,
/// Src: FromBytes + IntoBytes + NoCell,
/// Dst: FromBytes + IntoBytes + NoCell,
/// size_of::<Src>() == size_of::<Dst>(),
/// align_of::<Src>() >= align_of::<Dst>(),
/// {
/// # /*
/// ...
/// # */
/// }
/// ```
///
/// However, unlike a function, this macro can only be invoked when the types of
/// `Src` and `Dst` are completely concrete. The types `Src` and `Dst` are
/// inferred from the calling context; they cannot be explicitly specified in
/// the macro invocation.
///
/// # Examples
///
Expand Down

0 comments on commit 423beb7

Please sign in to comment.