Struct Assume

struct Assume { ... }

Configurable proof assumptions of TransmuteFrom.

When false, the respective proof obligation belongs to the compiler. When true, the onus of the safety proof belongs to the programmer.

Fields

alignment: bool

When false, TransmuteFrom is not implemented for transmutations that might violate the alignment requirements of references; e.g.:

#![feature(transmutability)]
use core::mem::TransmuteFrom;

assert_eq!(align_of::<[u8; 2]>(), 1);
assert_eq!(align_of::<u16>(), 2);

let src: &[u8; 2] = &[0xFF, 0xFF];

// SAFETY: No safety obligations.
let dst: &u16 = unsafe {
    <_ as TransmuteFrom<_>>::transmute(src)
};

When true, TransmuteFrom assumes that you have ensured that references in the transmuted value satisfy the alignment requirements of their referent types; e.g.:

#![feature(pointer_is_aligned_to, transmutability)]
use core::mem::{Assume, TransmuteFrom};

let src: &[u8; 2] = &[0xFF, 0xFF];

let maybe_dst: Option<&u16> = if <*const _>::is_aligned_to(src, align_of::<u16>()) {
    // SAFETY: We have checked above that the address of `src` satisfies the
    // alignment requirements of `u16`.
    Some(unsafe {
        <_ as TransmuteFrom<_, { Assume::ALIGNMENT }>>::transmute(src)
    })
} else {
    None
};

assert!(matches!(maybe_dst, Some(&u16::MAX) | None));
lifetimes: bool

When false, TransmuteFrom is not implemented for transmutations that extend the lifetimes of references.

When true, TransmuteFrom assumes that you have ensured that references in the transmuted value do not outlive their referents.

safety: bool

When false, TransmuteFrom is not implemented for transmutations that might violate the library safety invariants of the destination type; e.g.:

#![feature(transmutability)]
use core::mem::TransmuteFrom;

let src: u8 = 3;

struct EvenU8 {
    // SAFETY: `val` must be an even number.
    val: u8,
}

// SAFETY: No safety obligations.
let dst: EvenU8 = unsafe {
    <_ as TransmuteFrom<_>>::transmute(src)
};

When true, TransmuteFrom assumes that you have ensured that undefined behavior does not arise from using the transmuted value; e.g.:

#![feature(transmutability)]
use core::mem::{Assume, TransmuteFrom};

let src: u8 = 42;

struct EvenU8 {
    // SAFETY: `val` must be an even number.
    val: u8,
}

let maybe_dst: Option<EvenU8> = if src % 2 == 0 {
    // SAFETY: We have checked above that the value of `src` is even.
    Some(unsafe {
        <_ as TransmuteFrom<_, { Assume::SAFETY }>>::transmute(src)
    })
} else {
    None
};

assert!(matches!(maybe_dst, Some(EvenU8 { val: 42 })));
validity: bool

When false, TransmuteFrom is not implemented for transmutations that might violate the language-level bit-validity invariant of the destination type; e.g.:

#![feature(transmutability)]
use core::mem::TransmuteFrom;

let src: u8 = 3;

// SAFETY: No safety obligations.
let dst: bool = unsafe {
    <_ as TransmuteFrom<_>>::transmute(src)
};

When true, TransmuteFrom assumes that you have ensured that the value being transmuted is a bit-valid instance of the transmuted value; e.g.:

#![feature(transmutability)]
use core::mem::{Assume, TransmuteFrom};

let src: u8 = 1;

let maybe_dst: Option<bool> = if src == 0 || src == 1 {
    // SAFETY: We have checked above that the value of `src` is a bit-valid
    // instance of `bool`.
    Some(unsafe {
        <_ as TransmuteFrom<_, { Assume::VALIDITY }>>::transmute(src)
    })
} else {
    None
};

assert_eq!(maybe_dst, Some(true));

Implementations

impl Assume

const fn and(self: Self, other_assumptions: Self) -> Self

Combine the assumptions of self and other_assumptions.

This is especially useful for extending Assume in generic contexts; e.g.:

#![feature(
    adt_const_params,
    generic_const_exprs,
    pointer_is_aligned_to,
    transmutability,
)]
#![allow(incomplete_features)]
use core::mem::{Assume, TransmuteFrom};

/// Attempts to transmute `src` to `&Dst`.
///
/// Returns `None` if `src` violates the alignment requirements of `&Dst`.
///
/// # Safety
///
/// The caller guarantees that the obligations required by `ASSUME`, except
/// alignment, are satisfied.
unsafe fn try_transmute_ref<'a, Src, Dst, const ASSUME: Assume>(src: &'a Src) -> Option<&'a Dst>
where
    &'a Dst: TransmuteFrom<&'a Src, { ASSUME.and(Assume::ALIGNMENT) }>,
{
    if <*const _>::is_aligned_to(src, align_of::<Dst>()) {
        // SAFETY: By the above dynamic check, we have ensured that the address
        // of `src` satisfies the alignment requirements of `&Dst`. By contract
        // on the caller, the safety obligations required by `ASSUME` have also
        // been satisfied.
        Some(unsafe {
            <_ as TransmuteFrom<_, { ASSUME.and(Assume::ALIGNMENT) }>>::transmute(src)
        })
    } else {
        None
    }
}

let src: &[u8; 2] = &[0xFF, 0xFF];

// SAFETY: No safety obligations.
let maybe_dst: Option<&u16> = unsafe {
    try_transmute_ref::<_, _, { Assume::NOTHING }>(src)
};

const fn but_not(self: Self, other_assumptions: Self) -> Self

Remove other_assumptions the obligations of self; e.g.:

#![feature(transmutability)]
use core::mem::Assume;

let assumptions = Assume::ALIGNMENT.and(Assume::SAFETY);
let to_be_removed = Assume::SAFETY.and(Assume::VALIDITY);

assert_eq!(
    assumptions.but_not(to_be_removed),
    Assume::ALIGNMENT,
);

impl Add for Assume

fn add(self: Self, other_assumptions: Assume) -> Assume

impl Clone for Assume

fn clone(self: &Self) -> Assume

impl ConstParamTy_ for Assume

impl Copy for Assume

impl Debug for Assume

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result

impl Eq for Assume

impl Freeze for Assume

impl PartialEq for Assume

fn eq(self: &Self, other: &Assume) -> bool

impl RefUnwindSafe for Assume

impl Send for Assume

impl StructuralPartialEq for Assume

impl Sub for Assume

fn sub(self: Self, other_assumptions: Assume) -> Assume

impl Sync for Assume

impl Unpin for Assume

impl UnsafeUnpin for Assume

impl UnwindSafe for Assume

impl<T> Any for Assume

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Assume

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Assume

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for Assume

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for Assume

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Assume

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Assume

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Assume

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>