next_gen_transmute/

lib.rs

//! Stable backport of the unstable
//! [Next-Gen Transmute](https://github.com/rust-lang/rust/issues/155079) functions
//! [`transmute_prefix`] and [`transmute_neo`] to Rust 1.56

#![no_std]

use core::mem::{size_of, ManuallyDrop};

/// Like [`transmute`](`core::mem::transmute`), but only initializes the "common prefix" of the
/// first `min(size_of::<Src>(), size_of::<Dst>())` bytes of the destination from the
/// corresponding bytes of the source.
///
/// This is equivalent to a "union cast" through a `union` with `#[repr(C)]`.
///
/// That means some size mismatches are not UB, like `[T; 2]` to `[T; 1]`.
/// Increasing size is usually UB from being insufficiently initialized -- like
/// `u8` to `u32` -- but isn't always.  For example, going from `u8` to
/// `#[repr(C, align(4))] AlignedU8(u8);` is sound.
///
/// Prefer normal `transmute` where possible, for the extra checking, since
/// both do exactly the same thing at runtime, if they both compile.
///
/// # Safety
///
/// If `size_of::<Src>() >= size_of::<Dst>()`, the first `size_of::<Dst>()` bytes
/// of `src` must be be *valid* when interpreted as a `Dst`.  (In this case, the
/// preconditions are the same as for `transmute_copy(&ManuallyDrop::new(src))`.)
///
/// If `size_of::<Src>() <= size_of::<Dst>()`, the bytes of `src` padded with
/// uninitialized bytes afterwards up to a total size of `size_of::<Dst>()`
/// must be *valid* when interpreted as a `Dst`.
///
/// In both cases, any safety preconditions of the `Dst` type must also be upheld.
///
/// # Examples
///
/// ```
/// use next_gen_transmute::transmute_prefix;
///
/// assert_eq!(unsafe { transmute_prefix::<[i32; 4], [i32; 2]>([1, 2, 3, 4]) }, [1, 2]);
///
/// let expected = if cfg!(target_endian = "little") { 0x34 } else { 0x12 };
/// assert_eq!(unsafe { transmute_prefix::<u16, u8>(0x1234) }, expected);
///
/// // Would be UB because the destination is incompletely initialized.
/// // transmute_prefix::<u8, u16>(123)
///
/// // OK because the destination is allowed to be partially initialized.
/// let _: std::mem::MaybeUninit<u16> = unsafe { transmute_prefix(123_u8) };
/// ```
pub const unsafe fn transmute_prefix<Src, Dst>(src: Src) -> Dst {
    #[repr(C)]
    union Transmute<A, B> {
        a: ManuallyDrop<A>,
        b: ManuallyDrop<B>,
    }

    // SAFETY: any safety invariants need to be upheld by the caller.
    #[allow(unused_unsafe)]
    unsafe {
        ManuallyDrop::into_inner(
            Transmute {
                a: ManuallyDrop::new(src),
            }
            .b,
        )
    }
}

/// New version of `transmute`, exposed under this name so it can be iterated upon
/// without risking breakage to uses of "real" transmute.
///
/// It will not be stabilized under this name.
///
/// # Examples
///
/// ```
/// use next_gen_transmute::transmute_neo;
///
/// assert_eq!(unsafe { transmute_neo::<f32, u32>(0.0) }, 0);
/// ```
///
/// ```compile_fail,E0080
/// use next_gen_transmute::transmute_neo;
///
/// unsafe { transmute_neo::<u32, u16>(123) };
/// ```
pub const unsafe fn transmute_neo<Src, Dst>(src: Src) -> Dst {
    struct AssertSameSize<A, B>(A, B);
    impl<A, B> AssertSameSize<A, B> {
        const ASSERT_SAME_SIZE: () = [()][!(size_of::<A>() == size_of::<B>()) as usize];
    }
    let () = AssertSameSize::<Src, Dst>::ASSERT_SAME_SIZE;

    // SAFETY: the const-assert just checked that they're the same size,
    // and any other safety invariants need to be upheld by the caller.
    #[allow(unused_unsafe)]
    unsafe {
        transmute_prefix(src)
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use core::mem::MaybeUninit;

    const U32_4: [u32; 4] = [0x23456789, 0x456789AB, 0x6789ABCD, 0x89ABCDEF];
    const U32_2: [u32; 2] = [U32_4[0], U32_4[1]];
    const U32: u32 = U32_4[0];
    const I32_4: [i32; 4] = [U32_4[0] as _, U32_4[1] as _, U32_4[2] as _, U32_4[3] as _];
    const U8_4_2: [[u8; 4]; 2] = [U32_2[0].to_ne_bytes(), U32_2[1].to_ne_bytes()];
    const U8_8: [u8; 8] = [
        U8_4_2[0][0],
        U8_4_2[0][1],
        U8_4_2[0][2],
        U8_4_2[0][3],
        U8_4_2[1][0],
        U8_4_2[1][1],
        U8_4_2[1][2],
        U8_4_2[1][3],
    ];

    #[derive(Debug, PartialEq)]
    #[repr(C, align(8))]
    struct Align8U32(u32);

    #[test]
    fn bigger_to_smaller() {
        assert!(U32_4.len() >= U32_2.len());
        // SAFETY: every `[u32; M]` is a valid prefix of `[u32; N]` where `N >= M`.
        let x: [u32; U32_2.len()] = unsafe { transmute_prefix(U32_4) };
        assert_eq!(x, U32_2);
    }

    #[test]
    fn smaller_to_bigger() {
        // SAFETY: the destination does not have to be fully initialized.
        let mut x: [MaybeUninit<u32>; U32_4.len()] = unsafe { transmute_prefix(U32_2) };
        for i in U32_2.len()..U32_4.len() {
            x[i].write(U32_4[i]);
        }
        // SAFETY: the source is now fully initialized.
        let y: [u32; U32_4.len()] = unsafe { transmute_neo(x) };
        assert_eq!(y, U32_4);
    }

    #[test]
    fn array_to_first_element() {
        assert!(U32_4.len() >= 1);
        // SAFETY: every `u32` is a valid prefix of `[u32; N]` where `N >= 1`.
        let x: u32 = unsafe { transmute_prefix(U32_4) };
        assert_eq!(x, U32);
    }

    #[test]
    fn first_element_to_array() {
        // SAFETY: the destination does not have to be fully initialized.
        let mut x: [MaybeUninit<u32>; U32_4.len()] = unsafe { transmute_prefix(U32) };
        for i in 1..U32_4.len() {
            x[i].write(U32_4[i]);
        }
        // SAFETY: the source is now fully initialized.
        let y: [u32; U32_4.len()] = unsafe { transmute_neo(x) };
        assert_eq!(y, U32_4);
    }

    #[test]
    fn decrease_alignment() {
        // SAFETY: every `u32` is a valid prefix of `Align8U32`.
        let x: u32 = unsafe { transmute_prefix(Align8U32(U32)) };
        assert_eq!(x, U32);
    }

    #[test]
    fn increase_alignment() {
        // SAFETY: every `u32` is a valid prefix of `Align8U32`,
        // and the rest does not have to be initialized.
        let x: Align8U32 = unsafe { transmute_prefix(U32) };
        assert_eq!(x, Align8U32(U32));
    }

    #[test]
    fn cast_signed() {
        // SAFETY: every `[u32; 4]` is a valid `[i32; 4]`.
        let x: [i32; U32_4.len()] = unsafe { transmute_neo(U32_4) };
        assert_eq!(x, I32_4);
    }

    #[test]
    fn cast_unsigned() {
        // SAFETY: every `[i32; 4]` is a valid `[u32; 4]`.
        let x: [u32; I32_4.len()] = unsafe { transmute_neo(I32_4) };
        assert_eq!(x, U32_4);
    }

    #[test]
    fn from_ne_bytes() {
        // SAFETY: every `[u8; 4]` is a valid `u32`.
        let x: [u32; U8_8.len() / 4] = unsafe { transmute_neo(U8_8) };
        assert_eq!(x, U32_2);
    }

    #[test]
    fn to_ne_bytes() {
        // SAFETY: every `u32` is a valid `[u8; 4]`.
        let y: [u8; U32_2.len() * 4] = unsafe { transmute_neo(U32_2) };
        assert_eq!(y, U8_8);
    }
}