Struct zerocopy::Ref

source ·
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,

source

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.

source

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.

source

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,

source

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.

source

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.

source

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,

source

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.

source

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.

source

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,

source

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.

source

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.

source

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>
where B: ByteSlice, T: Unaligned,

source

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.

source

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.

source

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]>
where B: ByteSlice, T: Unaligned,

source

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.

source

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.

source

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,

source

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.

source

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.

source

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,

source

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.

source

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.

source

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>
where B: 'a + ByteSlice, T: FromBytes,

source

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

Converts this Ref into a reference.

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

source§

impl<'a, B, T> Ref<B, T>
where B: 'a + ByteSliceMut, T: FromBytes + AsBytes,

source

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.

source§

impl<'a, B, T> Ref<B, [T]>
where B: 'a + ByteSlice, T: FromBytes,

source

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]>
where B: 'a + ByteSliceMut, T: FromBytes + AsBytes,

source

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: ByteSlice, T: ?Sized,

source

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

Gets the underlying bytes.

source§

impl<B, T> Ref<B, T>
where B: ByteSliceMut, T: ?Sized,

source

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

Gets the underlying bytes mutably.

source§

impl<B, T> Ref<B, T>
where B: ByteSlice, T: FromBytes,

source

pub fn read(&self) -> T

Reads a copy of T.

source§

impl<B, T> Ref<B, T>
where B: ByteSliceMut, T: AsBytes,

source

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

Writes the bytes of t and then forgets t.

Trait Implementations§

source§

impl<T, B> Debug for Ref<B, [T]>
where B: ByteSlice, T: FromBytes + Debug,

source§

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

Formats the value using the given formatter. Read more
source§

impl<T, B> Debug for Ref<B, T>
where B: ByteSlice, T: FromBytes + Debug,

source§

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

Formats the value using the given formatter. Read more
source§

impl<B, T> Deref for Ref<B, [T]>
where B: ByteSlice, T: FromBytes,

source§

type Target = [T]

The resulting type after dereferencing.
source§

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

Dereferences the value.
source§

impl<B, T> Deref for Ref<B, T>
where B: ByteSlice, T: FromBytes,

source§

type Target = T

The resulting type after dereferencing.
source§

fn deref(&self) -> &T

Dereferences the value.
source§

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

source§

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

Mutably dereferences the value.
source§

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

source§

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

Mutably dereferences the value.
source§

impl<T, B> Display for Ref<B, [T]>
where B: ByteSlice, T: FromBytes, [T]: Display,

source§

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

Formats the value using the given formatter. Read more
source§

impl<T, B> Display for Ref<B, T>
where B: ByteSlice, T: FromBytes + Display,

source§

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

Formats the value using the given formatter. Read more
source§

impl<T, B> Ord for Ref<B, [T]>
where B: ByteSlice, T: FromBytes + Ord,

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

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

Restrict a value to a certain interval. Read more
source§

impl<T, B> Ord for Ref<B, T>
where B: ByteSlice, T: FromBytes + Ord,

source§

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

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

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

Restrict a value to a certain interval. Read more
source§

impl<T, B> PartialEq for Ref<B, [T]>
where B: ByteSlice, T: FromBytes + PartialEq,

source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

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

impl<T, B> PartialEq for Ref<B, T>
where B: ByteSlice, T: FromBytes + PartialEq,

source§

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

Tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

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

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

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

source§

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

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

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

impl<T, B> Eq for Ref<B, [T]>
where B: ByteSlice, T: FromBytes + Eq,

source§

impl<T, B> Eq for Ref<B, T>
where B: ByteSlice, T: FromBytes + Eq,

Auto Trait Implementations§

§

impl<B, T> Freeze for Ref<B, T>
where B: Freeze, T: ?Sized,

§

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

§

impl<B, T> Send for Ref<B, T>
where B: Send, T: Send + ?Sized,

§

impl<B, T> Sync for Ref<B, T>
where B: Sync, T: Sync + ?Sized,

§

impl<B, T> Unpin for Ref<B, T>
where B: Unpin, T: Unpin + ?Sized,

§

impl<B, T> UnwindSafe for Ref<B, T>
where B: UnwindSafe, T: UnwindSafe + ?Sized,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.