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 bit pattern is valid.

Any memory region of the appropriate length which contains initialized bytes can be viewed as any FromBytes type with no runtime overhead. This is useful for efficiently parsing bytes as structured data.

Implementation

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

#[derive(FromZeroes, FromBytes)]
struct MyStruct {
    ...
}

#[derive(FromZeroes, FromBytes)]
#[repr(u8)]
enum MyEnum {
    ...
}

#[derive(FromZeroes, FromBytes)]
union MyUnion {
    ...
}

This derive performs a sophisticated, compile-time safety analysis to determine whether a type is FromBytes.

Safety

This section describes what is required in order for T: FromBytes, and what unsafe code may assume of such types. 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>(), 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.

#[derive(FromBytes)] only permits types which satisfy these requirements.

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::<Self>() or bytes is not aligned to align_of::<Self>(), this returns None.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These bytes encode a `PacketHeader`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7].as_slice();

let header = PacketHeader::ref_from(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

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::<Self>() or bytes is not aligned to align_of::<Self>(), 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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These are more bytes than are needed to encode a `PacketHeader`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let header = PacketHeader::ref_from_prefix(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

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::<Self>() or the suffix of bytes is not aligned to align_of::<Self>(), 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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let trailer = PacketTrailer::ref_from_suffix(bytes).unwrap();

assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

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::<Self>() or bytes is not aligned to align_of::<Self>(), this returns None.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These bytes encode a `PacketHeader`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];

let header = PacketHeader::mut_from(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

header.checksum = [0, 0];

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0]);

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::<Self>() or bytes is not aligned to align_of::<Self>(), 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.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These are more bytes than are needed to encode a `PacketHeader`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let header = PacketHeader::mut_from_prefix(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

header.checksum = [0, 0];

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0, 8, 9]);

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::<Self>() or the suffix of bytes is not aligned to align_of::<Self>(), 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.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let trailer = PacketTrailer::mut_from_suffix(bytes).unwrap();

assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

trailer.frame_check_sequence = [0, 0, 0, 0];

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0, 0, 0]);

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

where Self: Sized,

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

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

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

Panics

If Self is a zero-sized type.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These bytes encode two `Pixel`s.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7].as_slice();

let pixels = Pixel::slice_from(bytes).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let (pixels, rest) = Pixel::slice_from_prefix(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

assert_eq!(rest, &[8, 9]);

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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let (rest, pixels) = Pixel::slice_from_suffix(bytes, 2).unwrap();

assert_eq!(rest, &[0, 1]);

assert_eq!(pixels, &[
    Pixel { r: 2, g: 3, b: 4, a: 5 },
    Pixel { r: 6, g: 7, b: 8, a: 9 },
]);

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.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These bytes encode two `Pixel`s.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];

let pixels = Pixel::mut_slice_from(bytes).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

assert_eq!(bytes, [0, 1, 2, 3, 0, 0, 0, 0]);

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.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (pixels, rest) = Pixel::mut_slice_from_prefix(bytes, 2).unwrap();

assert_eq!(pixels, &[
    Pixel { r: 0, g: 1, b: 2, a: 3 },
    Pixel { r: 4, g: 5, b: 6, a: 7 },
]);

assert_eq!(rest, &[8, 9]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

assert_eq!(bytes, [0, 1, 2, 3, 0, 0, 0, 0, 8, 9]);

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.

Examples

use zerocopy::FromBytes;

#[derive(AsBytes, FromZeroes, FromBytes)]
#[repr(C)]
struct Pixel {
    r: u8,
    g: u8,
    b: u8,
    a: u8,
}

// These are more bytes than are needed to encode two `Pixel`s.
let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7, 8, 9][..];

let (rest, pixels) = Pixel::mut_slice_from_suffix(bytes, 2).unwrap();

assert_eq!(rest, &[0, 1]);

assert_eq!(pixels, &[
    Pixel { r: 2, g: 3, b: 4, a: 5 },
    Pixel { r: 6, g: 7, b: 8, a: 9 },
]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

assert_eq!(bytes, [0, 1, 2, 3, 4, 5, 0, 0, 0, 0]);

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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These bytes encode a `PacketHeader`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7].as_slice();

let header = PacketHeader::read_from(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

// These are more bytes than are needed to encode a `PacketHeader`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let header = PacketHeader::read_from_prefix(bytes).unwrap();

assert_eq!(header.src_port, [0, 1]);
assert_eq!(header.dst_port, [2, 3]);
assert_eq!(header.length, [4, 5]);
assert_eq!(header.checksum, [6, 7]);

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.

Examples

use zerocopy::FromBytes;

#[derive(FromZeroes, FromBytes)]
#[repr(C)]
struct PacketTrailer {
    frame_check_sequence: [u8; 4],
}

// These are more bytes than are needed to encode a `PacketTrailer`.
let bytes = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9].as_slice();

let trailer = PacketTrailer::read_from_suffix(bytes).unwrap();

assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

Implementations on Foreign Types

impl FromBytes for Option<NonZeroI8>

impl FromBytes for Option<NonZeroI16>

impl FromBytes for Option<NonZeroI32>

impl FromBytes for Option<NonZeroI64>

impl FromBytes for Option<NonZeroI128>

impl FromBytes for Option<NonZeroIsize>

impl FromBytes for Option<NonZeroU8>

impl FromBytes for Option<NonZeroU16>

impl FromBytes for Option<NonZeroU32>

impl FromBytes for Option<NonZeroU64>

impl FromBytes for Option<NonZeroU128>

impl FromBytes for Option<NonZeroUsize>

impl FromBytes for f32

impl FromBytes for f64

impl FromBytes for i8

impl FromBytes for i16

impl FromBytes for i32

impl FromBytes for i64

impl FromBytes for i128

impl FromBytes for isize

impl FromBytes for u8

impl FromBytes for u16

impl FromBytes for u32

impl FromBytes for u64

impl FromBytes for u128

impl FromBytes for ()

impl FromBytes for usize

impl FromBytes for __m128

impl FromBytes for __m128d

impl FromBytes for __m128i

impl FromBytes for __m256

impl FromBytes for __m256d

impl FromBytes for __m256i

impl<T: FromBytes> FromBytes for [T]

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

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

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

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

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

Implementors

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