Trait zerocopy::FromBytes

source ·
pub unsafe trait FromBytes: FromZeroes {
Show 15 methods // 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 { ... }
}
Expand description

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§

source

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]);
source

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]);
source

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]);
source

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]);
source

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]);
source

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]);
source

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 },
]);
source

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]);
source

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 },
]);
source

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]);
source

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]);
source

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]);
source

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]);
source

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]);
source

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§

source§

impl FromBytes for Option<NonZeroI8>

source§

impl FromBytes for Option<NonZeroI16>

source§

impl FromBytes for Option<NonZeroI32>

source§

impl FromBytes for Option<NonZeroI64>

source§

impl FromBytes for Option<NonZeroI128>

source§

impl FromBytes for Option<NonZeroIsize>

source§

impl FromBytes for Option<NonZeroU8>

source§

impl FromBytes for Option<NonZeroU16>

source§

impl FromBytes for Option<NonZeroU32>

source§

impl FromBytes for Option<NonZeroU64>

source§

impl FromBytes for Option<NonZeroU128>

source§

impl FromBytes for Option<NonZeroUsize>

source§

impl FromBytes for f32

source§

impl FromBytes for f64

source§

impl FromBytes for i8

source§

impl FromBytes for i16

source§

impl FromBytes for i32

source§

impl FromBytes for i64

source§

impl FromBytes for i128

source§

impl FromBytes for isize

source§

impl FromBytes for u8

source§

impl FromBytes for u16

source§

impl FromBytes for u32

source§

impl FromBytes for u64

source§

impl FromBytes for u128

source§

impl FromBytes for ()

source§

impl FromBytes for usize

source§

impl FromBytes for __m128

source§

impl FromBytes for __m128d

source§

impl FromBytes for __m128i

source§

impl FromBytes for __m256

source§

impl FromBytes for __m256d

source§

impl FromBytes for __m256i

source§

impl<T: FromBytes> FromBytes for [T]

source§

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

source§

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

source§

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

source§

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

source§

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

Implementors§