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 aT
. - Given
b: &[u8]
whereb.len() == size_of::<T>()
,b
is aligned toalign_of::<T>()
it is sound to construct at: &T
at the same address asb
, and it is sound for bothb
andt
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§
sourcefn ref_from(bytes: &[u8]) -> Option<&Self>where
Self: Sized,
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]);
sourcefn ref_from_prefix(bytes: &[u8]) -> Option<&Self>where
Self: Sized,
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]);
sourcefn ref_from_suffix(bytes: &[u8]) -> Option<&Self>where
Self: Sized,
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]);
sourcefn mut_from(bytes: &mut [u8]) -> Option<&mut Self>
fn mut_from(bytes: &mut [u8]) -> Option<&mut Self>
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]);
sourcefn mut_from_prefix(bytes: &mut [u8]) -> Option<&mut Self>
fn mut_from_prefix(bytes: &mut [u8]) -> Option<&mut Self>
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]);
sourcefn mut_from_suffix(bytes: &mut [u8]) -> Option<&mut Self>
fn mut_from_suffix(bytes: &mut [u8]) -> Option<&mut Self>
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]);
sourcefn slice_from(bytes: &[u8]) -> Option<&[Self]>where
Self: Sized,
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 },
]);
sourcefn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>where
Self: Sized,
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]);
sourcefn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>where
Self: Sized,
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 },
]);
sourcefn mut_slice_from(bytes: &mut [u8]) -> Option<&mut [Self]>
fn mut_slice_from(bytes: &mut [u8]) -> Option<&mut [Self]>
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]);
sourcefn mut_slice_from_prefix(
bytes: &mut [u8],
count: usize,
) -> Option<(&mut [Self], &mut [u8])>
fn mut_slice_from_prefix( bytes: &mut [u8], count: usize, ) -> Option<(&mut [Self], &mut [u8])>
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]);
sourcefn mut_slice_from_suffix(
bytes: &mut [u8],
count: usize,
) -> Option<(&mut [u8], &mut [Self])>
fn mut_slice_from_suffix( bytes: &mut [u8], count: usize, ) -> Option<(&mut [u8], &mut [Self])>
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]);
sourcefn read_from(bytes: &[u8]) -> Option<Self>where
Self: Sized,
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]);
sourcefn read_from_prefix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
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]);
sourcefn read_from_suffix(bytes: &[u8]) -> Option<Self>where
Self: Sized,
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]);