Trait zerocopy::FromBytes

pub unsafe trait FromBytes: FromZeroes {
    // Provided methods
    fn ref_from(bytes: &[u8]) -> Option<&Self>
       where Self: Sized { ... }
    fn ref_from_prefix(bytes: &[u8]) -> Option<&Self>
       where Self: Sized { ... }
    fn ref_from_suffix(bytes: &[u8]) -> Option<&Self>
       where Self: Sized { ... }
    fn mut_from(bytes: &mut [u8]) -> Option<&mut Self>
       where Self: Sized + AsBytes { ... }
    fn mut_from_prefix(bytes: &mut [u8]) -> Option<&mut Self>
       where Self: Sized + AsBytes { ... }
    fn mut_from_suffix(bytes: &mut [u8]) -> Option<&mut Self>
       where Self: Sized + AsBytes { ... }
    fn slice_from(bytes: &[u8]) -> Option<&[Self]>
       where Self: Sized { ... }
    fn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>
       where Self: Sized { ... }
    fn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>
       where Self: Sized { ... }
    fn mut_slice_from(bytes: &mut [u8]) -> Option<&mut [Self]>
       where Self: Sized + AsBytes { ... }
    fn mut_slice_from_prefix(
        bytes: &mut [u8],
        count: usize
    ) -> Option<(&mut [Self], &mut [u8])>
       where Self: Sized + AsBytes { ... }
    fn mut_slice_from_suffix(
        bytes: &mut [u8],
        count: usize
    ) -> Option<(&mut [u8], &mut [Self])>
       where Self: Sized + AsBytes { ... }
    fn read_from(bytes: &[u8]) -> Option<Self>
       where Self: Sized { ... }
    fn read_from_prefix(bytes: &[u8]) -> Option<Self>
       where Self: Sized { ... }
    fn read_from_suffix(bytes: &[u8]) -> Option<Self>
       where Self: Sized { ... }
}

Types for which any byte pattern is valid.

WARNING: Do not implement this trait yourself! Instead, use #[derive(FromBytes)] (requires the derive Cargo feature).

FromBytes types can safely be deserialized from an untrusted sequence of bytes because any byte sequence corresponds to a valid instance of the type.

FromBytes is ignorant of byte order. For byte order-aware types, see the [byteorder] module.

Safety

This section describes what is required in order for T: FromBytes, and what unsafe code may assume of such types. #[derive(FromBytes)] only permits types which satisfy these requirements. If you don’t plan on implementing FromBytes manually, and you don’t plan on writing unsafe code that operates on FromBytes types, then you don’t need to read this section.

If T: FromBytes, then unsafe code may assume that:

• It is sound to treat any initialized sequence of bytes of length size_of::<T>() as a T.
• Given b: &[u8] where b.len() == size_of::<T>() and b is aligned to align_of::<T>(), it is sound to construct a t: &T at the same address as b, and it is sound for both b and t to be live at the same time.

If a type is marked as FromBytes which violates this contract, it may cause undefined behavior.

If a type has the following properties, then it is sound to implement FromBytes for that type:

• If the type is a struct, all of its fields must satisfy the requirements to be FromBytes (they do not actually have to be FromBytes)
• If the type is an enum:
  • It must be a C-like enum (meaning that all variants have no fields).
  • It must have a defined representation (reprs C, u8, u16, u32, u64, usize, i8, i16, i32, i64, or isize).
  • The maximum number of discriminants must be used (so that every possible bit pattern is a valid one). Be very careful when using the C, usize, or isize representations, as their size is platform-dependent.
• The type must not contain any UnsafeCells (this is required in order for it to be sound to construct a &[u8] and a &T to the same region of memory). The type may contain references or pointers to UnsafeCells so long as those values can themselves be initialized from zeroes (FromBytes is not currently implemented for, e.g., Option<*const UnsafeCell<_>>, but it could be one day).

Rationale

Why isn’t an explicit representation required for structs?

Per the Rust reference,

The representation of a type can change the padding between fields, but does not change the layout of the fields themselves.

Since the layout of structs only consists of padding bytes and field bytes, a struct is soundly FromBytes if:

1. its padding is soundly FromBytes, and
2. its fields are soundly FromBytes.

The answer to the first question is always yes: padding bytes do not have any validity constraints. A discussion of this question in the Unsafe Code Guidelines Working Group concluded that it would be virtually unimaginable for future versions of rustc to add validity constraints to padding bytes.

Whether a struct is soundly FromBytes therefore solely depends on whether its fields are FromBytes.

Provided Methods

fn ref_from(bytes: &[u8]) -> Option<&Self>where Self: Sized,

Interprets the given bytes as a &Self without copying.

If bytes.len() != size_of::<T>() or bytes is not aligned to align_of::<T>(), this returns None.

fn ref_from_prefix(bytes: &[u8]) -> Option<&Self>where Self: Sized,

Interprets the prefix of the given bytes as a &Self without copying.

ref_from_prefix returns a reference to the first size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<T>() or bytes is not aligned to align_of::<T>(), this returns None.

To also access the prefix bytes, use Ref::new_from_prefix. Then, use Ref::into_ref to get a &Self with the same lifetime.

fn ref_from_suffix(bytes: &[u8]) -> Option<&Self>where Self: Sized,

Interprets the suffix of the given bytes as a &Self without copying.

ref_from_suffix returns a reference to the last size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<T>() or the suffix of bytes is not aligned to align_of::<T>(), this returns None.

To also access the suffix bytes, use Ref::new_from_suffix. Then, use Ref::into_ref to get a &Self with the same lifetime.

fn mut_from(bytes: &mut [u8]) -> Option<&mut Self>where Self: Sized + AsBytes,

Interprets the given bytes as a &mut Self without copying.

If bytes.len() != size_of::<T>() or bytes is not aligned to align_of::<T>(), this returns None.

fn mut_from_prefix(bytes: &mut [u8]) -> Option<&mut Self>where Self: Sized + AsBytes,

Interprets the prefix of the given bytes as a &mut Self without copying.

mut_from_prefix returns a reference to the first size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<T>() or bytes is not aligned to align_of::<T>(), this returns None.

To also access the prefix bytes, use Ref::new_from_prefix. Then, use Ref::into_mut to get a &mut Self with the same lifetime.

fn mut_from_suffix(bytes: &mut [u8]) -> Option<&mut Self>where Self: Sized + AsBytes,

Interprets the suffix of the given bytes as a &mut Self without copying.

mut_from_suffix returns a reference to the last size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<T>() or the suffix of bytes is not aligned to align_of::<T>(), this returns None.

To also access the suffix bytes, use Ref::new_from_suffix. Then, use Ref::into_mut to get a &mut Self with the same lifetime.

fn slice_from(bytes: &[u8]) -> Option<&[Self]>where Self: Sized,

Interprets the given bytes as a &[Self] without copying.

If bytes.len() % size_of::<T>() != 0 or bytes is not aligned to align_of::<T>(), this returns None.

If you need to convert a specific number of slice elements, see slice_from_prefix or slice_from_suffix.

Panics

If T is a zero-sized type.

fn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>where Self: Sized,

Interprets the prefix of the given bytes as a &[Self] with length equal to count without copying.

This method verifies that bytes.len() >= size_of::<T>() * count and that bytes is aligned to align_of::<T>(). It consumes the first size_of::<T>() * count bytes from bytes to construct a &[Self], and returns the remaining bytes to the caller. It also ensures that sizeof::<T>() * count does not overflow a usize. If any of the length, alignment, or overflow checks fail, it returns None.

Panics

If T is a zero-sized type.

fn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>where Self: Sized,

Interprets the suffix of the given bytes as a &[Self] with length equal to count without copying.

This method verifies that bytes.len() >= size_of::<T>() * count and that bytes is aligned to align_of::<T>(). It consumes the last size_of::<T>() * count bytes from bytes to construct a &[Self], and returns the preceding bytes to the caller. It also ensures that sizeof::<T>() * count does not overflow a usize. If any of the length, alignment, or overflow checks fail, it returns None.

Panics

If T is a zero-sized type.

fn mut_slice_from(bytes: &mut [u8]) -> Option<&mut [Self]>where Self: Sized + AsBytes,

Interprets the given bytes as a &mut [Self] without copying.

If bytes.len() % size_of::<T>() != 0 or bytes is not aligned to align_of::<T>(), this returns None.

If you need to convert a specific number of slice elements, see mut_slice_from_prefix or mut_slice_from_suffix.

Panics

If T is a zero-sized type.

fn mut_slice_from_prefix( bytes: &mut [u8], count: usize ) -> Option<(&mut [Self], &mut [u8])>where Self: Sized + AsBytes,

Interprets the prefix of the given bytes as a &mut [Self] with length equal to count without copying.

This method verifies that bytes.len() >= size_of::<T>() * count and that bytes is aligned to align_of::<T>(). It consumes the first size_of::<T>() * count bytes from bytes to construct a &[Self], and returns the remaining bytes to the caller. It also ensures that sizeof::<T>() * count does not overflow a usize. If any of the length, alignment, or overflow checks fail, it returns None.

Panics

If T is a zero-sized type.

fn mut_slice_from_suffix( bytes: &mut [u8], count: usize ) -> Option<(&mut [u8], &mut [Self])>where Self: Sized + AsBytes,

Interprets the suffix of the given bytes as a &mut [Self] with length equal to count without copying.

This method verifies that bytes.len() >= size_of::<T>() * count and that bytes is aligned to align_of::<T>(). It consumes the last size_of::<T>() * count bytes from bytes to construct a &[Self], and returns the preceding bytes to the caller. It also ensures that sizeof::<T>() * count does not overflow a usize. If any of the length, alignment, or overflow checks fail, it returns None.

Panics

If T is a zero-sized type.

fn read_from(bytes: &[u8]) -> Option<Self>where Self: Sized,

Reads a copy of Self from bytes.

If bytes.len() != size_of::<Self>(), read_from returns None.

fn read_from_prefix(bytes: &[u8]) -> Option<Self>where Self: Sized,

Reads a copy of Self from the prefix of bytes.

read_from_prefix reads a Self from the first size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<Self>(), it returns None.

fn read_from_suffix(bytes: &[u8]) -> Option<Self>where Self: Sized,

Reads a copy of Self from the suffix of bytes.

read_from_suffix reads a Self from the last size_of::<Self>() bytes of bytes. If bytes.len() < size_of::<Self>(), it returns None.

Implementations on Foreign Types

impl<T: FromBytes> FromBytes for MaybeUninit<T>

impl<T: FromBytes> FromBytes for [T]

impl FromBytes for __m256d

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

impl FromBytes for Option<NonZeroI8>

impl<T: FromBytes> FromBytes for Wrapping<T>

impl FromBytes for f64

impl FromBytes for __m256

impl FromBytes for f32

impl FromBytes for Option<NonZeroI16>

impl FromBytes for __m128d

impl FromBytes for i32

impl FromBytes for __m256i

impl FromBytes for u128

impl FromBytes for Option<NonZeroU8>

impl FromBytes for i128

impl FromBytes for u32

impl FromBytes for __m128i

impl FromBytes for Option<NonZeroU16>

impl FromBytes for isize

impl FromBytes for usize

impl FromBytes for i64

impl FromBytes for u16

impl FromBytes for Option<NonZeroU32>

impl FromBytes for Option<NonZeroI64>

impl FromBytes for Option<NonZeroI32>

impl FromBytes for i8

impl FromBytes for i16

impl FromBytes for Option<NonZeroU64>

impl FromBytes for ()

impl FromBytes for Option<NonZeroI128>

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

impl FromBytes for u8

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

impl FromBytes for __m128

impl FromBytes for Option<NonZeroU128>

impl FromBytes for u64

impl FromBytes for Option<NonZeroUsize>

impl FromBytes for Option<NonZeroIsize>

Implementors

impl<T: FromBytes> FromBytes for Unalign<T>