Struct zerocopy::LayoutVerified

pub struct LayoutVerified<B, T: ?Sized>(_, _);

A length- and alignment-checked reference to a byte slice which can safely be reinterpreted as another type.

LayoutVerified is a byte slice reference (&[u8], &mut [u8], Ref<[u8]>, RefMut<[u8]>, etc) with the invaraint that the slice’s length and alignment are each greater than or equal to the length and alignment of T. Using this invariant, it implements Deref for T so long as T: FromBytes and DerefMut so long as T: FromBytes + AsBytes.

Examples

LayoutVerified 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, LayoutVerified, Unaligned};

#[derive(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: LayoutVerified<B, UdpHeader>,
    body: B,
}

impl<B: ByteSlice> UdpPacket<B> {
    pub fn parse(bytes: B) -> Option<UdpPacket<B>> {
        let (header, body) = LayoutVerified::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> LayoutVerified<B, T> where
    B: ByteSlice, 

pub fn new(bytes: B) -> Option<LayoutVerified<B, T>>

Constructs a new LayoutVerified.

new verifies that bytes.len() == size_of::<T>() and that bytes is aligned to align_of::<T>(), and constructs a new LayoutVerified. If either of these checks fail, it returns None.

pub fn new_from_prefix(bytes: B) -> Option<(LayoutVerified<B, T>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, T>)>

Constructs a new LayoutVerified 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 LayoutVerified, and returns the preceding bytes to the caller. If either the length or alignment checks fail, it returns None.

impl<B, T> LayoutVerified<B, [T]> where
    B: ByteSlice, 

pub fn new_slice(bytes: B) -> Option<LayoutVerified<B, [T]>>

Constructs a new LayoutVerified 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 LayoutVerified. 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<(LayoutVerified<B, [T]>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, [T]>)>

Constructs a new LayoutVerified 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 LayoutVerified, 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> LayoutVerified<B, T> where
    B: ByteSliceMut, 

pub fn new_zeroed(bytes: B) -> Option<LayoutVerified<B, T>>

Constructs a new LayoutVerified 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 LayoutVerified. 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<(LayoutVerified<B, T>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, T>)>

Constructs a new LayoutVerified 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 LayoutVerified, 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> LayoutVerified<B, [T]> where
    B: ByteSliceMut, 

pub fn new_slice_zeroed(bytes: B) -> Option<LayoutVerified<B, [T]>>

Constructs a new LayoutVerified 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 LayoutVerified. 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<(LayoutVerified<B, [T]>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, [T]>)>

Constructs a new LayoutVerified 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 LayoutVerified, 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> LayoutVerified<B, T> where
    B: ByteSlice,
    T: Unaligned, 

pub fn new_unaligned(bytes: B) -> Option<LayoutVerified<B, T>>

Constructs a new LayoutVerified for a type with no alignment requirement.

new_unaligned verifies that bytes.len() == size_of::<T>() and constructs a new LayoutVerified. If the check fails, it returns None.

pub fn new_unaligned_from_prefix(bytes: B) -> Option<(LayoutVerified<B, T>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, T>)>

Constructs a new LayoutVerified 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 LayoutVerified, and returns the preceding bytes to the caller. If the length check fails, it returns None.

impl<B, T> LayoutVerified<B, [T]> where
    B: ByteSlice,
    T: Unaligned, 

pub fn new_slice_unaligned(bytes: B) -> Option<LayoutVerified<B, [T]>>

Constructs a new LayoutVerified 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 LayoutVerified. 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<(LayoutVerified<B, [T]>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, [T]>)>

Constructs a new LayoutVerified 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 LayoutVerified, 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> LayoutVerified<B, T> where
    B: ByteSliceMut,
    T: Unaligned, 

pub fn new_unaligned_zeroed(bytes: B) -> Option<LayoutVerified<B, T>>

Constructs a new LayoutVerified for a type with no alignment requirement, zeroing the bytes.

new_unaligned_zeroed verifies that bytes.len() == size_of::<T>() and constructs a new LayoutVerified. 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<(LayoutVerified<B, T>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, T>)>

Constructs a new LayoutVerified 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 LayoutVerified, 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> LayoutVerified<B, [T]> where
    B: ByteSliceMut,
    T: Unaligned, 

pub fn new_slice_unaligned_zeroed(bytes: B) -> Option<LayoutVerified<B, [T]>>

Constructs a new LayoutVerified 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 LayoutVerified. 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<(LayoutVerified<B, [T]>, B)>

Constructs a new LayoutVerified 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 LayoutVerified, 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, LayoutVerified<B, [T]>)>

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

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

Converts this LayoutVerified into a reference.

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

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

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

Converts this LayoutVerified into a mutable reference.

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

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

pub fn into_slice(self) -> &'a [T]

Converts this LayoutVerified into a slice reference.

into_slice consumes the LayoutVerified, and returns a reference to [T].

impl<'a, B, T> LayoutVerified<B, [T]> where
    B: 'a + ByteSliceMut,
    T: FromBytes + AsBytes, 

pub fn into_mut_slice(self) -> &'a mut [T]

Converts this LayoutVerified into a mutable slice reference.

into_mut_slice consumes the LayoutVerified, and returns a mutable reference to [T].

impl<B, T> LayoutVerified<B, T> where
    B: ByteSlice,
    T: ?Sized, 

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

Gets the underlying bytes.

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

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

Gets the underlying bytes mutably.

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

pub fn read(&self) -> T

Reads a copy of T.

impl<B, T> LayoutVerified<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 LayoutVerified<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 LayoutVerified<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 LayoutVerified<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 LayoutVerified<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 LayoutVerified<B, T> where
    B: ByteSliceMut,
    T: FromBytes + AsBytes, 

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

Mutably dereferences the value.

impl<B, T> DerefMut for LayoutVerified<B, [T]> where
    B: ByteSliceMut,
    T: FromBytes + AsBytes, 

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

Mutably dereferences the value.

impl<T, B> Display for LayoutVerified<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> Display for LayoutVerified<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> Ord for LayoutVerified<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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl<T, B> Ord for LayoutVerified<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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl<T, B> PartialOrd<LayoutVerified<B, [T]>> for LayoutVerified<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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl<T, B> PartialOrd<LayoutVerified<B, T>> for LayoutVerified<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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

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

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