Struct Ref

pub struct Ref<B, T: ?Sized>(/* private fields */);

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

impl<B, T> Ref<B, T>

where B: ByteSlice,

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.

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.

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.

impl<B, T> Ref<B, [T]>

where B: ByteSlice,

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.

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.

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.

impl<B, T> Ref<B, T>

where B: ByteSliceMut,

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.

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.

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.

impl<B, T> Ref<B, [T]>

where B: ByteSliceMut,

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.

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.

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.

impl<B, T> Ref<B, T>

where B: ByteSlice, T: Unaligned,

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.

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.

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.

impl<B, T> Ref<B, [T]>

where B: ByteSlice, T: Unaligned,

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.

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.

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.

impl<B, T> Ref<B, T>

where B: ByteSliceMut, T: Unaligned,

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.

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.

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.

impl<B, T> Ref<B, [T]>

where B: ByteSliceMut, T: Unaligned,

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.

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.

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.

impl<'a, B, T> Ref<B, T>

where B: 'a + ByteSlice, T: FromBytes,

pub fn into_ref(self) -> &'a T

Converts this Ref into a reference.

into_ref consumes the Ref, and returns a reference to T.

impl<'a, B, T> Ref<B, T>

where B: 'a + ByteSliceMut, T: FromBytes + AsBytes,

pub fn into_mut(self) -> &'a mut T

Converts this Ref into a mutable reference.

into_mut consumes the Ref, and returns a mutable reference to T.

impl<'a, B, T> Ref<B, [T]>

where B: 'a + ByteSlice, T: FromBytes,

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].

impl<'a, B, T> Ref<B, [T]>

where B: 'a + ByteSliceMut, T: FromBytes + AsBytes,

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].

impl<B, T> Ref<B, T>

where B: ByteSlice, T: ?Sized,

pub fn bytes(&self) -> &[u8]

Gets the underlying bytes.

impl<B, T> Ref<B, T>

where B: ByteSliceMut, T: ?Sized,

pub fn bytes_mut(&mut self) -> &mut [u8]

Gets the underlying bytes mutably.

impl<B, T> Ref<B, T>

where B: ByteSlice, T: FromBytes,

pub fn read(&self) -> T

Reads a copy of T.

impl<B, T> Ref<B, T>

where B: ByteSliceMut, T: AsBytes,

pub fn write(&mut self, t: T)

Writes the bytes of t and then forgets t.

Trait Implementations

impl<T, B> Debug for Ref<B, [T]>

where B: ByteSlice, T: FromBytes + Debug,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, B> Debug for Ref<B, T>

where B: ByteSlice, T: FromBytes + Debug,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B, T> Deref for Ref<B, [T]>

where B: ByteSlice, T: FromBytes,

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<B, T> Deref for Ref<B, T>

where B: ByteSlice, T: FromBytes,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<B, T> DerefMut for Ref<B, [T]>

where B: ByteSliceMut, T: FromBytes + AsBytes,

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<B, T> DerefMut for Ref<B, T>

where B: ByteSliceMut, T: FromBytes + AsBytes,

fn deref_mut(&mut self) -> &mut T

Mutably dereferences the value.

impl<T, B> Display for Ref<B, [T]>

where B: ByteSlice, T: FromBytes, [T]: Display,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, B> Display for Ref<B, T>

where B: ByteSlice, T: FromBytes + Display,

fn fmt(&self, fmt: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T, B> Ord for Ref<B, [T]>

where B: ByteSlice, T: FromBytes + Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, B> Ord for Ref<B, T>

where B: ByteSlice, T: FromBytes + Ord,

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T, B> PartialEq for Ref<B, [T]>

where B: ByteSlice, T: FromBytes + PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, B> PartialEq for Ref<B, T>

where B: ByteSlice, T: FromBytes + PartialEq,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T, B> PartialOrd for Ref<B, [T]>

where B: ByteSlice, T: FromBytes + PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, B> PartialOrd for Ref<B, T>

where B: ByteSlice, T: FromBytes + PartialOrd,

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T, B> Eq for Ref<B, [T]>

where B: ByteSlice, T: FromBytes + Eq,

impl<T, B> Eq for Ref<B, T>

where B: ByteSlice, T: FromBytes + Eq,

Layout

Note: Unable to compute type layout, possibly due to this type having generic parameters. Layout can only be computed for concrete, fully-instantiated types.