Trait FromBytes

pub unsafe trait FromBytes: FromZeros {
    // Provided methods
    fn ref_from_bytes(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>>
       where Self: KnownLayout + Immutable { ... }
    fn ref_from_prefix(
        source: &[u8],
    ) -> Result<(&Self, &[u8]), CastError<&[u8], Self>>
       where Self: KnownLayout + Immutable { ... }
    fn ref_from_suffix(
        source: &[u8],
    ) -> Result<(&[u8], &Self), CastError<&[u8], Self>>
       where Self: Immutable + KnownLayout { ... }
    fn mut_from_bytes(
        source: &mut [u8],
    ) -> Result<&mut Self, CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout { ... }
    fn mut_from_prefix(
        source: &mut [u8],
    ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout { ... }
    fn mut_from_suffix(
        source: &mut [u8],
    ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout { ... }
    fn ref_from_bytes_with_elems(
        source: &[u8],
        count: usize,
    ) -> Result<&Self, CastError<&[u8], Self>>
       where Self: KnownLayout<PointerMetadata = usize> + Immutable { ... }
    fn ref_from_prefix_with_elems(
        source: &[u8],
        count: usize,
    ) -> Result<(&Self, &[u8]), CastError<&[u8], Self>>
       where Self: KnownLayout<PointerMetadata = usize> + Immutable { ... }
    fn ref_from_suffix_with_elems(
        source: &[u8],
        count: usize,
    ) -> Result<(&[u8], &Self), CastError<&[u8], Self>>
       where Self: KnownLayout<PointerMetadata = usize> + Immutable { ... }
    fn mut_from_bytes_with_elems(
        source: &mut [u8],
        count: usize,
    ) -> Result<&mut Self, CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout<PointerMetadata = usize> + Immutable { ... }
    fn mut_from_prefix_with_elems(
        source: &mut [u8],
        count: usize,
    ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout<PointerMetadata = usize> { ... }
    fn mut_from_suffix_with_elems(
        source: &mut [u8],
        count: usize,
    ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>
       where Self: IntoBytes + KnownLayout<PointerMetadata = usize> { ... }
    fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>
       where Self: Sized { ... }
    fn read_from_prefix(
        source: &[u8],
    ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>
       where Self: Sized { ... }
    fn read_from_suffix(
        source: &[u8],
    ) -> Result<(&[u8], Self), SizeError<&[u8], 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.

Warning: Padding bytes

Note that, when a value is moved or copied, only the non-padding bytes of that value are guaranteed to be preserved. It is unsound to assume that values written to padding bytes are preserved after a move or copy. For example, the following is unsound:

use core::mem::{size_of, transmute};
use zerocopy::FromZeros;

// Assume `Foo` is a type with padding bytes.
#[derive(FromZeros, Default)]
struct Foo {
    ...
}

let mut foo: Foo = Foo::default();
FromZeros::zero(&mut foo);
// UNSOUND: Although `FromZeros::zero` writes zeros to all bytes of `foo`,
// those writes are not guaranteed to be preserved in padding bytes when
// `foo` is moved, so this may expose padding bytes as `u8`s.
let foo_bytes: [u8; size_of::<Foo>()] = unsafe { transmute(foo) };

Implementation

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

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

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

#[derive(FromBytes, Immutable)]
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 produce a T whose bytes are initialized to any sequence of valid u8s (in other words, any byte value which is not uninitialized). 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(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Interprets the given source as a &Self.

This method attempts to return a reference to source interpreted as a Self. If the length of source is not a valid size of Self, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_bytes(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

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

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Packet {
    header: PacketHeader,
    body: [u8],
}

// These bytes encode a `Packet`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11][..];

let packet = Packet::ref_from_bytes(bytes).unwrap();

assert_eq!(packet.header.src_port, [0, 1]);
assert_eq!(packet.header.dst_port, [2, 3]);
assert_eq!(packet.header.length, [4, 5]);
assert_eq!(packet.header.checksum, [6, 7]);
assert_eq!(packet.body, [8, 9, 10, 11]);

fn ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), CastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

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

This method computes the largest possible size of Self that can fit in the leading bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See ref_from_prefix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_prefix(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

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

#[derive(FromBytes, KnownLayout, Immutable)]
#[repr(C)]
struct Packet {
    header: PacketHeader,
    body: [[u8; 2]],
}

// These are more bytes than are needed to encode a `Packet`.
let bytes = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14][..];

let (packet, suffix) = Packet::ref_from_prefix(bytes).unwrap();

assert_eq!(packet.header.src_port, [0, 1]);
assert_eq!(packet.header.dst_port, [2, 3]);
assert_eq!(packet.header.length, [4, 5]);
assert_eq!(packet.header.checksum, [6, 7]);
assert_eq!(packet.body, [[8, 9], [10, 11], [12, 13]]);
assert_eq!(suffix, &[14u8][..]);

fn ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), CastError<&[u8], Self>>

where Self: Immutable + KnownLayout,

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

This method computes the largest possible size of Self that can fit in the trailing bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See ref_from_suffix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = ZSTy::ref_from_suffix(0u16.as_bytes()); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, Immutable, KnownLayout)]
#[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][..];

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

assert_eq!(prefix, &[0, 1, 2, 3, 4, 5][..]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

fn mut_from_bytes( source: &mut [u8], ) -> Result<&mut Self, CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

This method attempts to return a reference to source interpreted as a Self. If the length of source is not a valid size of Self, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See mut_from_prefix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_bytes(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[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(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( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

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

This method computes the largest possible size of Self that can fit in the leading bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. See mut_from_suffix_with_elems, which does support such types. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_prefix(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[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, body) = 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]);
assert_eq!(body, &[8, 9][..]);

header.checksum = [0, 0];
body.fill(1);

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

fn mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

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

This method computes the largest possible size of Self that can fit in the trailing bytes of source, then attempts to return both a reference to those bytes interpreted as a Self, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Self may be a sized type, a slice, or a slice DST.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(FromBytes, Immutable, IntoBytes, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let mut source = [85, 85];
let _ = ZSTy::mut_from_suffix(&mut source[..]); // ⚠ Compile Error!

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[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 (prefix, trailer) = PacketTrailer::mut_from_suffix(bytes).unwrap();

assert_eq!(prefix, &[0u8, 1, 2, 3, 4, 5][..]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

prefix.fill(0);
trailer.frame_check_sequence.fill(1);

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

fn ref_from_bytes_with_elems( source: &[u8], count: usize, ) -> Result<&Self, CastError<&[u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &Self with a DST length equal to count.

This method attempts to return a reference to source interpreted as a Self with count trailing elements. If the length of source is not equal to the size of Self with count elements, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

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

let bytes = &[0, 1, 2, 3, 4, 5, 6, 7][..];

let pixels = <[Pixel]>::ref_from_bytes_with_elems(bytes, 2).unwrap();

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

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_bytes which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let zsty = ZSTy::ref_from_bytes_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn ref_from_prefix_with_elems( source: &[u8], count: usize, ) -> Result<(&Self, &[u8]), CastError<&[u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the prefix of the given source as a DST &Self with length equal to count.

This method attempts to return a reference to the prefix of source interpreted as a Self with count trailing elements, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, Immutable)]
#[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][..];

let (pixels, suffix) = <[Pixel]>::ref_from_prefix_with_elems(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!(suffix, &[8, 9]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_prefix which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let (zsty, _) = ZSTy::ref_from_prefix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn ref_from_suffix_with_elems( source: &[u8], count: usize, ) -> Result<(&[u8], &Self), CastError<&[u8], Self>>

where Self: KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the suffix of the given source as a DST &Self with length equal to count.

This method attempts to return a reference to the suffix of source interpreted as a Self with count trailing elements, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, Immutable)]
#[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][..];

let (prefix, pixels) = <[Pixel]>::ref_from_suffix_with_elems(bytes, 2).unwrap();

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

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

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as ref_from_suffix which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &[85, 85][..];
let (_, zsty) = ZSTy::ref_from_suffix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn mut_from_bytes_with_elems( source: &mut [u8], count: usize, ) -> Result<&mut Self, CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize> + Immutable,

Interprets the given source as a &mut Self with a DST length equal to count.

This method attempts to return a reference to source interpreted as a Self with count trailing elements. If the length of source is not equal to the size of Self with count elements, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

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

let bytes = &mut [0, 1, 2, 3, 4, 5, 6, 7][..];

let pixels = <[Pixel]>::mut_from_bytes_with_elems(bytes, 2).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]);

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let zsty = ZSTy::mut_from_bytes_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn mut_from_prefix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the prefix of the given source as a &mut Self with DST length equal to count.

This method attempts to return a reference to the prefix of source interpreted as a Self with count trailing elements, and a reference to the preceding bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

#[derive(KnownLayout, FromBytes, IntoBytes, Immutable)]
#[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, suffix) = <[Pixel]>::mut_from_prefix_with_elems(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!(suffix, &[8, 9]);

pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };
suffix.fill(1);

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

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from_prefix which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let (zsty, _) = ZSTy::mut_from_prefix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn mut_from_suffix_with_elems( source: &mut [u8], count: usize, ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout<PointerMetadata = usize>,

Interprets the suffix of the given source as a &mut Self with DST length equal to count.

This method attempts to return a reference to the suffix of source interpreted as a Self with count trailing elements, and a reference to the remaining bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If Self: Unaligned, you can infallibly discard the alignment error.

Examples

use zerocopy::FromBytes;

#[derive(FromBytes, IntoBytes, Immutable)]
#[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 (prefix, pixels) = <[Pixel]>::mut_from_suffix_with_elems(bytes, 2).unwrap();

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

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

prefix.fill(9);
pixels[1] = Pixel { r: 0, g: 0, b: 0, a: 0 };

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

Since an explicit count is provided, this method supports types with zero-sized trailing slice elements. Methods such as mut_from_suffix which do not take an explicit count do not support such types.

use zerocopy::*;

#[derive(FromBytes, IntoBytes, Immutable, KnownLayout)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: [u8; 2],
    trailing_dst: [()],
}

let src = &mut [85, 85][..];
let (_, zsty) = ZSTy::mut_from_suffix_with_elems(src, 42).unwrap();
assert_eq!(zsty.trailing_dst.len(), 42);

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the given source.

If source.len() != size_of::<Self>(), read_from_bytes returns Err.

Examples

use zerocopy::FromBytes;

#[derive(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][..];

let header = PacketHeader::read_from_bytes(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( source: &[u8], ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the prefix of the given source.

This attempts to read a Self from the first size_of::<Self>() bytes of source, returning that Self and any remaining bytes. If source.len() < size_of::<Self>(), it returns Err.

Examples

use zerocopy::FromBytes;

#[derive(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][..];

let (header, body) = 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]);
assert_eq!(body, [8, 9]);

fn read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the suffix of the given source.

This attempts to read a Self from the last size_of::<Self>() bytes of source, returning that Self and any preceding bytes. If source.len() < size_of::<Self>(), it returns Err.

Examples

use zerocopy::FromBytes;

#[derive(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][..];

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

assert_eq!(prefix, [0, 1, 2, 3, 4, 5]);
assert_eq!(trailer.frame_check_sequence, [6, 7, 8, 9]);

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

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

Available on x86-64 and crate feature simd only.

impl FromBytes for __m128d

Available on x86-64 and crate feature simd only.

impl FromBytes for __m128i

Available on x86-64 and crate feature simd only.

impl FromBytes for __m256

Available on x86-64 and crate feature simd only.

impl FromBytes for __m256d

Available on x86-64 and crate feature simd only.

impl FromBytes for __m256i

Available on x86-64 and crate feature simd only.

impl FromBytes for AtomicI8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl FromBytes for AtomicI16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl FromBytes for AtomicI32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl FromBytes for AtomicI64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl FromBytes for AtomicIsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl FromBytes for AtomicU8

Available on target_has_atomic="8" and rust="1.60.0" only.

impl FromBytes for AtomicU16

Available on target_has_atomic="16" and rust="1.60.0" only.

impl FromBytes for AtomicU32

Available on target_has_atomic="32" and rust="1.60.0" only.

impl FromBytes for AtomicU64

Available on target_has_atomic="64" and rust="1.60.0" only.

impl FromBytes for AtomicUsize

Available on target_has_atomic="ptr" and rust="1.60.0" only.

impl<T> FromBytes for MaybeUninit<T>

impl<T: FromBytes> FromBytes for [T]

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

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

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

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

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

Implementors

impl<O> FromBytes for F32<O>

impl<O> FromBytes for F64<O>

impl<O> FromBytes for I16<O>

impl<O> FromBytes for I32<O>

impl<O> FromBytes for I64<O>

impl<O> FromBytes for I128<O>

impl<O> FromBytes for Isize<O>

impl<O> FromBytes for U16<O>

impl<O> FromBytes for U32<O>

impl<O> FromBytes for U64<O>

impl<O> FromBytes for U128<O>

impl<O> FromBytes for Usize<O>

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