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