core::mem

Struct Assume

source
pub struct Assume {
    pub alignment: bool,
    pub lifetimes: bool,
    pub safety: bool,
    pub validity: bool,
}
🔬This is a nightly-only experimental API. (transmutability #99571)
Expand description

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
🔬This is a nightly-only experimental API. (transmutability #99571)

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

ⓘ
#![feature(transmutability)]
use core::mem::{align_of, 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::{align_of, 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
🔬This is a nightly-only experimental API. (transmutability #99571)

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
🔬This is a nightly-only experimental API. (transmutability #99571)

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
🔬This is a nightly-only experimental API. (transmutability #99571)

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§

source§

impl Assume

source

pub const NOTHING: Self = _

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

With this, TransmuteFrom does not assume you have ensured any safety obligations are met, and relies only upon its own analysis to (dis)prove transmutability.

source

pub const ALIGNMENT: Self = _

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

With this, TransmuteFrom assumes only that you have ensured that references in the transmuted value satisfy the alignment requirements of their referent types. See Assume::alignment for examples.

source

pub const LIFETIMES: Self = _

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

With this, TransmuteFrom assumes only that you have ensured that references in the transmuted value do not outlive their referents. See Assume::lifetimes for examples.

source

pub const SAFETY: Self = _

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

With this, TransmuteFrom assumes only that you have ensured that undefined behavior does not arise from using the transmuted value. See Assume::safety for examples.

source

pub const VALIDITY: Self = _

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

With this, TransmuteFrom assumes only that you have ensured that the value being transmuted is a bit-valid instance of the transmuted value. See Assume::validity for examples.

source

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

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

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::{align_of, 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)
};
source

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

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

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,
);

Trait Implementations§

source§

impl Add for Assume

source§

type Output = Assume

The resulting type after applying the + operator.
source§

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

Performs the + operation. Read more
source§

impl Clone for Assume

source§

fn clone(&self) -> Assume

Returns a copy of the value. Read more
1.6.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl Debug for Assume

source§

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

Formats the value using the given formatter. Read more
source§

impl PartialEq for Assume

source§

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

Tests for self and other values to be equal, and is used by ==.
1.6.0 · source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Sub for Assume

source§

type Output = Assume

The resulting type after applying the - operator.
source§

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

Performs the - operation. Read more
source§

impl ConstParamTy_ for Assume

source§

impl Copy for Assume

source§

impl Eq for Assume

source§

impl StructuralPartialEq for Assume

source§

impl UnsizedConstParamTy for Assume

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit #126799)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.