Trait zerocopy::TryFromBytes

pub unsafe trait TryFromBytes {
    // Provided methods
    fn try_from_ref(bytes: &[u8]) -> Option<&Self>
       where Self: KnownLayout + NoCell { ... }
    fn try_from_mut(bytes: &mut [u8]) -> Option<&mut Self>
       where Self: KnownLayout + NoCell { ... }
    fn try_read_from(bytes: &[u8]) -> Option<Self>
       where Self: Sized { ... }
}

Types for which some bit patterns are valid.

A memory region of the appropriate length which contains initialized bytes can be viewed as a TryFromBytes type so long as the runtime value of those bytes corresponds to a valid instance of that type. For example, bool is TryFromBytes; zerocopy can transmute a [u8] into a bool so long as it first checks that the value of the [u8] is [0] or [1].

Implementation

Do not implement this trait yourself! Instead, use #[derive(TryFromBytes)] (requires the derive Cargo feature); e.g.:

#[derive(TryFromBytes)]
struct MyStruct {
    ...
}

#[derive(TryFromBytes)]
#[repr(u8)]
enum MyEnum {
    ...
}

#[derive(TryFromBytes, NoCell)]
union MyUnion {
    ...
}

This derive ensures that the runtime check of whether bytes correspond to a valid instance is sound. You must implement this trait via the derive.

What is a “valid instance”?

In Rust, each type has bit validity, which refers to the set of bit patterns which may appear in an instance of that type. It is impossible for safe Rust code to produce values which violate bit validity (ie, values outside of the “valid” set of bit patterns). If unsafe code produces an invalid value, this is considered undefined behavior.

Rust’s bit validity rules are currently being decided, which means that some types have three classes of bit patterns: those which are definitely valid, and whose validity is documented in the language; those which may or may not be considered valid at some point in the future; and those which are definitely invalid.

Zerocopy takes a conservative approach, and only considers a bit pattern to be valid if its validity is a documenteed guarantee provided by the language.

For most use cases, Rust’s current guarantees align with programmers’ intuitions about what ought to be valid. As a result, zerocopy’s conservatism should not affect most users. One notable exception is unions, whose bit validity is very up in the air; zerocopy does not permit implementing TryFromBytes for any union type.

If you are negatively affected by lack of support for a particular type, we encourage you to let us know by filing an issue.

TryFromBytes is not symmetrical with IntoBytes

There are some types which implement both TryFromBytes and IntoBytes, but for which TryFromBytes is not guaranteed to accept all byte sequences produced by IntoBytes. In other words, for some T: TryFromBytes + IntoBytes, there exist values of t: T such that TryFromBytes::try_from_ref(t.as_bytes()) == None. Code should not generally assume that values produced by IntoBytes will necessarily be accepted as valid by TryFromBytes.

Safety

On its own, T: TryFromBytes does not make any guarantees about the layout or representation of T. It merely provides the ability to perform a validity check at runtime via methods like try_from_ref.

You must not rely on the #[doc(hidden)] internals of TryFromBytes. Future releases of zerocopy may make backwards-breaking changes to these items, including changes that only affect soundness, which may cause code which uses those items to silently become unsound.

Provided Methods

fn try_from_ref(bytes: &[u8]) -> Option<&Self>

where Self: KnownLayout + NoCell,

Attempts to interpret a byte slice as a Self.

try_from_ref validates that bytes contains a valid Self, and that it satisfies Self’s alignment requirement. If it does, then bytes is reinterpreted as a Self.

Note that Rust’s bit validity rules are still being decided. As such, there exist types whose bit validity is ambiguous. See here for a discussion of how these cases are handled.

fn try_from_mut(bytes: &mut [u8]) -> Option<&mut Self>

where Self: KnownLayout + NoCell,

Attempts to interpret a mutable byte slice as a Self.

try_from_mut validates that bytes contains a valid Self, and that it satisfies Self’s alignment requirement. If it does, then bytes is reinterpreted as a Self.

Note that Rust’s bit validity rules are still being decided. As such, there exist types whose bit validity is ambiguous. See here for a discussion of how these cases are handled.

fn try_read_from(bytes: &[u8]) -> Option<Self>

where Self: Sized,

Attempts to read a Self from a byte slice.

try_read_from validates that bytes contains a valid Self. If it does, those bytes are read out of bytes and reinterpreted as a Self.

Note that Rust’s bit validity rules are still being decided. As such, there exist types whose bit validity is ambiguous. See here for a discussion of how these cases are handled.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl TryFromBytes for Option<NonZeroI8>

impl TryFromBytes for Option<NonZeroI16>

impl TryFromBytes for Option<NonZeroI32>

impl TryFromBytes for Option<NonZeroI64>

impl TryFromBytes for Option<NonZeroI128>

impl TryFromBytes for Option<NonZeroIsize>

impl TryFromBytes for Option<NonZeroU8>

impl TryFromBytes for Option<NonZeroU16>

impl TryFromBytes for Option<NonZeroU32>

impl TryFromBytes for Option<NonZeroU64>

impl TryFromBytes for Option<NonZeroU128>

impl TryFromBytes for Option<NonZeroUsize>

impl TryFromBytes for bool

impl TryFromBytes for char

impl TryFromBytes for f32

impl TryFromBytes for f64

impl TryFromBytes for i8

impl TryFromBytes for i16

impl TryFromBytes for i32

impl TryFromBytes for i64

impl TryFromBytes for i128

impl TryFromBytes for isize

impl TryFromBytes for str

impl TryFromBytes for u8

impl TryFromBytes for u16

impl TryFromBytes for u32

impl TryFromBytes for u64

impl TryFromBytes for u128

impl TryFromBytes for ()

impl TryFromBytes for usize

impl TryFromBytes for __m128

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m128d

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m128i

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m256

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m256d

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m256i

Available on x86-64 and crate feature simd only.

impl TryFromBytes for __m512

Available on crate feature simd-nightly and x86-64 and crate feature simd only.

impl TryFromBytes for __m512bh

Available on crate feature simd-nightly and x86-64 and crate feature simd only.

impl TryFromBytes for __m512d

Available on crate feature simd-nightly and x86-64 and crate feature simd only.

impl TryFromBytes for __m512i

Available on crate feature simd-nightly and x86-64 and crate feature simd only.

impl TryFromBytes for NonZeroI8

impl TryFromBytes for NonZeroI16

impl TryFromBytes for NonZeroI32

impl TryFromBytes for NonZeroI64

impl TryFromBytes for NonZeroI128

impl TryFromBytes for NonZeroIsize

impl TryFromBytes for NonZeroU8

impl TryFromBytes for NonZeroU16

impl TryFromBytes for NonZeroU32

impl TryFromBytes for NonZeroU64

impl TryFromBytes for NonZeroU128

impl TryFromBytes for NonZeroUsize

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<A, B, C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: A, _: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<B, C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<B, C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: B, _: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<C, D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: C, _: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<D, E, F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: D, _: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<E, F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<E, F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: E, _: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<F, G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<F, G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: F, _: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<G, H, I, J, K, L, M> TryFromBytes for Option<fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<G, H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: G, _: H, _: I, _: J, _: K, _: L) -> M>

impl<H, I, J, K, L, M> TryFromBytes for Option<fn(_: H, _: I, _: J, _: K, _: L) -> M>

impl<H, I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: H, _: I, _: J, _: K, _: L) -> M>

impl<I, J, K, L, M> TryFromBytes for Option<fn(_: I, _: J, _: K, _: L) -> M>

impl<I, J, K, L, M> TryFromBytes for Option<extern "C" fn(_: I, _: J, _: K, _: L) -> M>

impl<J, K, L, M> TryFromBytes for Option<fn(_: J, _: K, _: L) -> M>

impl<J, K, L, M> TryFromBytes for Option<extern "C" fn(_: J, _: K, _: L) -> M>

impl<K, L, M> TryFromBytes for Option<fn(_: K, _: L) -> M>

impl<K, L, M> TryFromBytes for Option<extern "C" fn(_: K, _: L) -> M>

impl<L, M> TryFromBytes for Option<fn(_: L) -> M>

impl<L, M> TryFromBytes for Option<extern "C" fn(_: L) -> M>

impl<M> TryFromBytes for Option<fn() -> M>

impl<M> TryFromBytes for Option<extern "C" fn() -> M>

impl<T> TryFromBytes for Option<&T>

impl<T> TryFromBytes for Option<&mut T>

impl<T> TryFromBytes for Option<Box<T>>

Available on crate feature alloc only.

impl<T> TryFromBytes for Option<NonNull<T>>

impl<T> TryFromBytes for *const T

impl<T> TryFromBytes for *mut T

impl<T> TryFromBytes for MaybeUninit<T>

impl<T: TryFromBytes> TryFromBytes for [T]

impl<T: TryFromBytes> TryFromBytes for UnsafeCell<T>

impl<T: TryFromBytes> TryFromBytes for Wrapping<T>

impl<T: TryFromBytes, const N: usize> TryFromBytes for [T; N]

impl<T: ?Sized + TryFromBytes> TryFromBytes for ManuallyDrop<T>

impl<T: ?Sized> TryFromBytes for PhantomData<T>

Implementors

impl<O> TryFromBytes for F32<O>

where [u8; 4]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for F64<O>

where [u8; 8]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for I16<O>

where [u8; 2]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for I32<O>

where [u8; 4]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for I64<O>

where [u8; 8]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for I128<O>

where [u8; 16]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for Isize<O>

where [u8; 8]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for U16<O>

where [u8; 2]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for U32<O>

where [u8; 4]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for U64<O>

where [u8; 8]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for U128<O>

where [u8; 16]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<O> TryFromBytes for Usize<O>

where [u8; 8]: TryFromBytes, PhantomData<O>: TryFromBytes,

impl<T> TryFromBytes for Unalign<T>

where T: TryFromBytes,