pub struct Ref<B, T: ?Sized>(/* private fields */);
Expand description
A typed reference derived from a byte slice.
A Ref<B, T>
is a reference to a T
which is stored in a byte slice, B
.
Unlike a native reference (&T
or &mut T
), Ref<B, T>
has the same
mutability as the byte slice it was constructed from (B
).
§Examples
Ref
can be used to treat a sequence of bytes as a structured type, and to
read and write the fields of that type as if the byte slice reference were
simply a reference to that type.
use zerocopy::{AsBytes, ByteSlice, ByteSliceMut, FromBytes, FromZeroes, Ref, Unaligned};
#[derive(FromZeroes, FromBytes, AsBytes, Unaligned)]
#[repr(C)]
struct UdpHeader {
src_port: [u8; 2],
dst_port: [u8; 2],
length: [u8; 2],
checksum: [u8; 2],
}
struct UdpPacket<B> {
header: Ref<B, UdpHeader>,
body: B,
}
impl<B: ByteSlice> UdpPacket<B> {
pub fn parse(bytes: B) -> Option<UdpPacket<B>> {
let (header, body) = Ref::new_unaligned_from_prefix(bytes)?;
Some(UdpPacket { header, body })
}
pub fn get_src_port(&self) -> [u8; 2] {
self.header.src_port
}
}
impl<B: ByteSliceMut> UdpPacket<B> {
pub fn set_src_port(&mut self, src_port: [u8; 2]) {
self.header.src_port = src_port;
}
}
Implementations§
source§impl<B, T> Ref<B, T>where
B: ByteSlice,
impl<B, T> Ref<B, T>where
B: ByteSlice,
sourcepub fn new(bytes: B) -> Option<Ref<B, T>>
pub fn new(bytes: B) -> Option<Ref<B, T>>
Constructs a new Ref
.
new
verifies that bytes.len() == size_of::<T>()
and that bytes
is
aligned to align_of::<T>()
, and constructs a new Ref
. If either of
these checks fail, it returns None
.
sourcepub fn new_from_prefix(bytes: B) -> Option<(Ref<B, T>, B)>
pub fn new_from_prefix(bytes: B) -> Option<(Ref<B, T>, B)>
Constructs a new Ref
from the prefix of a byte slice.
new_from_prefix
verifies that bytes.len() >= size_of::<T>()
and that
bytes
is aligned to align_of::<T>()
. It consumes the first
size_of::<T>()
bytes from bytes
to construct a Ref
, and returns
the remaining bytes to the caller. If either the length or alignment
checks fail, it returns None
.
sourcepub fn new_from_suffix(bytes: B) -> Option<(B, Ref<B, T>)>
pub fn new_from_suffix(bytes: B) -> Option<(B, Ref<B, T>)>
Constructs a new Ref
from the suffix of a byte slice.
new_from_suffix
verifies that bytes.len() >= size_of::<T>()
and that
the last size_of::<T>()
bytes of bytes
are aligned to
align_of::<T>()
. It consumes the last size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the preceding bytes to the
caller. If either the length or alignment checks fail, it returns
None
.
source§impl<B, T> Ref<B, [T]>where
B: ByteSlice,
impl<B, T> Ref<B, [T]>where
B: ByteSlice,
sourcepub fn new_slice(bytes: B) -> Option<Ref<B, [T]>>
pub fn new_slice(bytes: B) -> Option<Ref<B, [T]>>
Constructs a new Ref
of a slice type.
new_slice
verifies that bytes.len()
is a multiple of
size_of::<T>()
and that bytes
is aligned to align_of::<T>()
, and
constructs a new Ref
. If either of these checks fail, it returns
None
.
§Panics
new_slice
panics if T
is a zero-sized type.
sourcepub fn new_slice_from_prefix(bytes: B, count: usize) -> Option<(Ref<B, [T]>, B)>
pub fn new_slice_from_prefix(bytes: B, count: usize) -> Option<(Ref<B, [T]>, B)>
Constructs a new Ref
of a slice type from the prefix of a byte slice.
new_slice_from_prefix
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 Ref
,
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
new_slice_from_prefix
panics if T
is a zero-sized type.
sourcepub fn new_slice_from_suffix(bytes: B, count: usize) -> Option<(B, Ref<B, [T]>)>
pub fn new_slice_from_suffix(bytes: B, count: usize) -> Option<(B, Ref<B, [T]>)>
Constructs a new Ref
of a slice type from the suffix of a byte slice.
new_slice_from_suffix
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 Ref
,
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
new_slice_from_suffix
panics if T
is a zero-sized type.
source§impl<B, T> Ref<B, T>where
B: ByteSliceMut,
impl<B, T> Ref<B, T>where
B: ByteSliceMut,
sourcepub fn new_zeroed(bytes: B) -> Option<Ref<B, T>>
pub fn new_zeroed(bytes: B) -> Option<Ref<B, T>>
Constructs a new Ref
after zeroing the bytes.
new_zeroed
verifies that bytes.len() == size_of::<T>()
and that
bytes
is aligned to align_of::<T>()
, and constructs a new Ref
. If
either of these checks fail, it returns None
.
If the checks succeed, then bytes
will be initialized to zero. This
can be useful when re-using buffers to ensure that sensitive data
previously stored in the buffer is not leaked.
sourcepub fn new_from_prefix_zeroed(bytes: B) -> Option<(Ref<B, T>, B)>
pub fn new_from_prefix_zeroed(bytes: B) -> Option<(Ref<B, T>, B)>
Constructs a new Ref
from the prefix of a byte slice, zeroing the
prefix.
new_from_prefix_zeroed
verifies that bytes.len() >= size_of::<T>()
and that bytes
is aligned to align_of::<T>()
. It consumes the first
size_of::<T>()
bytes from bytes
to construct a Ref
, and returns
the remaining bytes to the caller. If either the length or alignment
checks fail, it returns None
.
If the checks succeed, then the prefix which is consumed will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
sourcepub fn new_from_suffix_zeroed(bytes: B) -> Option<(B, Ref<B, T>)>
pub fn new_from_suffix_zeroed(bytes: B) -> Option<(B, Ref<B, T>)>
Constructs a new Ref
from the suffix of a byte slice, zeroing the
suffix.
new_from_suffix_zeroed
verifies that bytes.len() >= size_of::<T>()
and that the last size_of::<T>()
bytes of bytes
are aligned to
align_of::<T>()
. It consumes the last size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the preceding bytes to the
caller. If either the length or alignment checks fail, it returns
None
.
If the checks succeed, then the suffix which is consumed will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
source§impl<B, T> Ref<B, [T]>where
B: ByteSliceMut,
impl<B, T> Ref<B, [T]>where
B: ByteSliceMut,
sourcepub fn new_slice_zeroed(bytes: B) -> Option<Ref<B, [T]>>
pub fn new_slice_zeroed(bytes: B) -> Option<Ref<B, [T]>>
Constructs a new Ref
of a slice type after zeroing the bytes.
new_slice_zeroed
verifies that bytes.len()
is a multiple of
size_of::<T>()
and that bytes
is aligned to align_of::<T>()
, and
constructs a new Ref
. If either of these checks fail, it returns
None
.
If the checks succeed, then bytes
will be initialized to zero. This
can be useful when re-using buffers to ensure that sensitive data
previously stored in the buffer is not leaked.
§Panics
new_slice
panics if T
is a zero-sized type.
sourcepub fn new_slice_from_prefix_zeroed(
bytes: B,
count: usize,
) -> Option<(Ref<B, [T]>, B)>
pub fn new_slice_from_prefix_zeroed( bytes: B, count: usize, ) -> Option<(Ref<B, [T]>, B)>
Constructs a new Ref
of a slice type from the prefix of a byte slice,
after zeroing the bytes.
new_slice_from_prefix
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 Ref
,
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
.
If the checks succeed, then the suffix which is consumed will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
§Panics
new_slice_from_prefix_zeroed
panics if T
is a zero-sized type.
sourcepub fn new_slice_from_suffix_zeroed(
bytes: B,
count: usize,
) -> Option<(B, Ref<B, [T]>)>
pub fn new_slice_from_suffix_zeroed( bytes: B, count: usize, ) -> Option<(B, Ref<B, [T]>)>
Constructs a new Ref
of a slice type from the prefix of a byte slice,
after zeroing the bytes.
new_slice_from_suffix
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 Ref
,
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
.
If the checks succeed, then the consumed suffix will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
§Panics
new_slice_from_suffix_zeroed
panics if T
is a zero-sized type.
source§impl<B, T> Ref<B, T>
impl<B, T> Ref<B, T>
sourcepub fn new_unaligned(bytes: B) -> Option<Ref<B, T>>
pub fn new_unaligned(bytes: B) -> Option<Ref<B, T>>
Constructs a new Ref
for a type with no alignment requirement.
new_unaligned
verifies that bytes.len() == size_of::<T>()
and
constructs a new Ref
. If the check fails, it returns None
.
sourcepub fn new_unaligned_from_prefix(bytes: B) -> Option<(Ref<B, T>, B)>
pub fn new_unaligned_from_prefix(bytes: B) -> Option<(Ref<B, T>, B)>
Constructs a new Ref
from the prefix of a byte slice for a type with
no alignment requirement.
new_unaligned_from_prefix
verifies that bytes.len() >= size_of::<T>()
. It consumes the first size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the remaining bytes to the
caller. If the length check fails, it returns None
.
sourcepub fn new_unaligned_from_suffix(bytes: B) -> Option<(B, Ref<B, T>)>
pub fn new_unaligned_from_suffix(bytes: B) -> Option<(B, Ref<B, T>)>
Constructs a new Ref
from the suffix of a byte slice for a type with
no alignment requirement.
new_unaligned_from_suffix
verifies that bytes.len() >= size_of::<T>()
. It consumes the last size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the preceding bytes to the
caller. If the length check fails, it returns None
.
source§impl<B, T> Ref<B, [T]>
impl<B, T> Ref<B, [T]>
sourcepub fn new_slice_unaligned(bytes: B) -> Option<Ref<B, [T]>>
pub fn new_slice_unaligned(bytes: B) -> Option<Ref<B, [T]>>
Constructs a new Ref
of a slice type with no alignment requirement.
new_slice_unaligned
verifies that bytes.len()
is a multiple of
size_of::<T>()
and constructs a new Ref
. If the check fails, it
returns None
.
§Panics
new_slice
panics if T
is a zero-sized type.
sourcepub fn new_slice_unaligned_from_prefix(
bytes: B,
count: usize,
) -> Option<(Ref<B, [T]>, B)>
pub fn new_slice_unaligned_from_prefix( bytes: B, count: usize, ) -> Option<(Ref<B, [T]>, B)>
Constructs a new Ref
of a slice type with no alignment requirement
from the prefix of a byte slice.
new_slice_from_prefix
verifies that bytes.len() >= size_of::<T>() * count
. It consumes the first size_of::<T>() * count
bytes from
bytes
to construct a Ref
, and returns the remaining bytes to the
caller. It also ensures that sizeof::<T>() * count
does not overflow a
usize
. If either the length, or overflow checks fail, it returns
None
.
§Panics
new_slice_unaligned_from_prefix
panics if T
is a zero-sized type.
sourcepub fn new_slice_unaligned_from_suffix(
bytes: B,
count: usize,
) -> Option<(B, Ref<B, [T]>)>
pub fn new_slice_unaligned_from_suffix( bytes: B, count: usize, ) -> Option<(B, Ref<B, [T]>)>
Constructs a new Ref
of a slice type with no alignment requirement
from the suffix of a byte slice.
new_slice_from_suffix
verifies that bytes.len() >= size_of::<T>() * count
. It consumes the last size_of::<T>() * count
bytes from bytes
to construct a Ref
, and returns the remaining bytes to the caller. It
also ensures that sizeof::<T>() * count
does not overflow a usize
.
If either the length, or overflow checks fail, it returns None
.
§Panics
new_slice_unaligned_from_suffix
panics if T
is a zero-sized type.
source§impl<B, T> Ref<B, T>where
B: ByteSliceMut,
T: Unaligned,
impl<B, T> Ref<B, T>where
B: ByteSliceMut,
T: Unaligned,
sourcepub fn new_unaligned_zeroed(bytes: B) -> Option<Ref<B, T>>
pub fn new_unaligned_zeroed(bytes: B) -> Option<Ref<B, T>>
Constructs a new Ref
for a type with no alignment requirement, zeroing
the bytes.
new_unaligned_zeroed
verifies that bytes.len() == size_of::<T>()
and
constructs a new Ref
. If the check fails, it returns None
.
If the check succeeds, then bytes
will be initialized to zero. This
can be useful when re-using buffers to ensure that sensitive data
previously stored in the buffer is not leaked.
sourcepub fn new_unaligned_from_prefix_zeroed(bytes: B) -> Option<(Ref<B, T>, B)>
pub fn new_unaligned_from_prefix_zeroed(bytes: B) -> Option<(Ref<B, T>, B)>
Constructs a new Ref
from the prefix of a byte slice for a type with
no alignment requirement, zeroing the prefix.
new_unaligned_from_prefix_zeroed
verifies that bytes.len() >= size_of::<T>()
. It consumes the first size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the remaining bytes to the
caller. If the length check fails, it returns None
.
If the check succeeds, then the prefix which is consumed will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
sourcepub fn new_unaligned_from_suffix_zeroed(bytes: B) -> Option<(B, Ref<B, T>)>
pub fn new_unaligned_from_suffix_zeroed(bytes: B) -> Option<(B, Ref<B, T>)>
Constructs a new Ref
from the suffix of a byte slice for a type with
no alignment requirement, zeroing the suffix.
new_unaligned_from_suffix_zeroed
verifies that bytes.len() >= size_of::<T>()
. It consumes the last size_of::<T>()
bytes from
bytes
to construct a Ref
, and returns the preceding bytes to the
caller. If the length check fails, it returns None
.
If the check succeeds, then the suffix which is consumed will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
source§impl<B, T> Ref<B, [T]>where
B: ByteSliceMut,
T: Unaligned,
impl<B, T> Ref<B, [T]>where
B: ByteSliceMut,
T: Unaligned,
sourcepub fn new_slice_unaligned_zeroed(bytes: B) -> Option<Ref<B, [T]>>
pub fn new_slice_unaligned_zeroed(bytes: B) -> Option<Ref<B, [T]>>
Constructs a new Ref
for a slice type with no alignment requirement,
zeroing the bytes.
new_slice_unaligned_zeroed
verifies that bytes.len()
is a multiple
of size_of::<T>()
and constructs a new Ref
. If the check fails, it
returns None
.
If the check succeeds, then bytes
will be initialized to zero. This
can be useful when re-using buffers to ensure that sensitive data
previously stored in the buffer is not leaked.
§Panics
new_slice
panics if T
is a zero-sized type.
sourcepub fn new_slice_unaligned_from_prefix_zeroed(
bytes: B,
count: usize,
) -> Option<(Ref<B, [T]>, B)>
pub fn new_slice_unaligned_from_prefix_zeroed( bytes: B, count: usize, ) -> Option<(Ref<B, [T]>, B)>
Constructs a new Ref
of a slice type with no alignment requirement
from the prefix of a byte slice, after zeroing the bytes.
new_slice_from_prefix
verifies that bytes.len() >= size_of::<T>() * count
. It consumes the first size_of::<T>() * count
bytes from
bytes
to construct a Ref
, and returns the remaining bytes to the
caller. It also ensures that sizeof::<T>() * count
does not overflow a
usize
. If either the length, or overflow checks fail, it returns
None
.
If the checks succeed, then the prefix will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
§Panics
new_slice_unaligned_from_prefix_zeroed
panics if T
is a zero-sized
type.
sourcepub fn new_slice_unaligned_from_suffix_zeroed(
bytes: B,
count: usize,
) -> Option<(B, Ref<B, [T]>)>
pub fn new_slice_unaligned_from_suffix_zeroed( bytes: B, count: usize, ) -> Option<(B, Ref<B, [T]>)>
Constructs a new Ref
of a slice type with no alignment requirement
from the suffix of a byte slice, after zeroing the bytes.
new_slice_from_suffix
verifies that bytes.len() >= size_of::<T>() * count
. It consumes the last size_of::<T>() * count
bytes from bytes
to construct a Ref
, and returns the remaining bytes to the caller. It
also ensures that sizeof::<T>() * count
does not overflow a usize
.
If either the length, or overflow checks fail, it returns None
.
If the checks succeed, then the suffix will be initialized to zero. This can be useful when re-using buffers to ensure that sensitive data previously stored in the buffer is not leaked.
§Panics
new_slice_unaligned_from_suffix_zeroed
panics if T
is a zero-sized
type.
source§impl<'a, B, T> Ref<B, [T]>
impl<'a, B, T> Ref<B, [T]>
sourcepub fn into_slice(self) -> &'a [T]
pub fn into_slice(self) -> &'a [T]
Converts this Ref
into a slice reference.
into_slice
consumes the Ref
, and returns a reference to [T]
.
source§impl<'a, B, T> Ref<B, [T]>
impl<'a, B, T> Ref<B, [T]>
sourcepub fn into_mut_slice(self) -> &'a mut [T]
pub fn into_mut_slice(self) -> &'a mut [T]
Converts this Ref
into a mutable slice reference.
into_mut_slice
consumes the Ref
, and returns a mutable reference to
[T]
.
source§impl<B, T> Ref<B, T>where
B: ByteSliceMut,
T: ?Sized,
impl<B, T> Ref<B, T>where
B: ByteSliceMut,
T: ?Sized,
Trait Implementations§
source§impl<T, B> Ord for Ref<B, [T]>
impl<T, B> Ord for Ref<B, [T]>
source§impl<T, B> Ord for Ref<B, T>
impl<T, B> Ord for Ref<B, T>
source§impl<T, B> PartialEq for Ref<B, [T]>
impl<T, B> PartialEq for Ref<B, [T]>
source§impl<T, B> PartialEq for Ref<B, T>
impl<T, B> PartialEq for Ref<B, T>
source§impl<T, B> PartialOrd for Ref<B, [T]>
impl<T, B> PartialOrd for Ref<B, [T]>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<T, B> PartialOrd for Ref<B, T>
impl<T, B> PartialOrd for Ref<B, T>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read more