Trait TransmuteFrom

pub unsafe trait TransmuteFrom<Src, const ASSUME: Assume = core::::mem::transmutability::TransmuteFrom::{constant#0}>
where
    Src: ?Sized,
{
    // Provided method
    unsafe fn transmute(src: Src) -> Self
       where Self: Sized { ... }
}

🔬This is a nightly-only experimental API. (transmutability)

Marks that Src is transmutable into Self.

Implementation

This trait cannot be implemented explicitly. It is implemented on-the-fly by the compiler for all types Src and Self such that, given a set of safety obligations on the programmer (see Assume), the compiler has proved that the bits of a value of type Src can be soundly reinterpreted as a Self.

Safety

If Dst: TransmuteFrom<Src, ASSUMPTIONS>, the compiler guarantees that Src is soundly union-transmutable into a value of type Dst, provided that the programmer has guaranteed that the given ASSUMPTIONS are satisfied.

A union-transmute is any bit-reinterpretation conversion in the form of:

pub unsafe fn transmute_via_union<Src, Dst>(src: Src) -> Dst {
    use core::mem::ManuallyDrop;

    #[repr(C)]
    union Transmute<Src, Dst> {
        src: ManuallyDrop<Src>,
        dst: ManuallyDrop<Dst>,
    }

    let transmute = Transmute {
        src: ManuallyDrop::new(src),
    };

    let dst = transmute.dst;

    ManuallyDrop::into_inner(dst)
}

Note that this construction is more permissive than mem::transmute_copy; union-transmutes permit conversions that extend the bits of Src with trailing padding to fill trailing uninitialized bytes of Self; e.g.:

#![feature(transmutability)]

use core::mem::{Assume, TransmuteFrom};

let src = 42u8; // size = 1

#[repr(C, align(2))]
struct Dst(u8); // size = 2
let _ = unsafe {
    <Dst as TransmuteFrom<u8, { Assume::SAFETY }>>::transmute(src)
};

Caveats

Portability

Implementations of this trait do not provide any guarantee of portability across toolchains, targets or compilations. This trait may be implemented for certain combinations of Src, Self and ASSUME on some toolchains, targets or compilations, but not others. For example, if the layouts of Src or Self