Struct zerocopy::LayoutVerified

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

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

#[repr(C)]
struct UdpHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

unsafe impl FromBytes for UdpHeader {}
unsafe impl AsBytes for UdpHeader {}
unsafe impl Unaligned for UdpHeader {}

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

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.

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

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: 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: 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,

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

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