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;
    }
}

Methods

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

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

Construct 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)>

Construct 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>)>

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

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

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

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

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

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

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

Construct 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)>

Construct 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>)>

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

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

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

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

Construct 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)>

Construct 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>)>

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

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

impl<B, T> LayoutVerified<B, T> where
    B: ByteSliceMut,
    T: Unaligned, 

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

Construct 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)>

Construct 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>)>

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

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

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

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

Convert 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

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

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

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

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

Trait Implementations

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