Struct zerocopy::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::{IntoBytes, ByteSliceMut, FromBytes, FromZeros, KnownLayout, Immutable, Ref, SplitByteSlice, Unaligned};

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, 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: SplitByteSlice> UdpPacket<B> {
    pub fn parse(bytes: B) -> Option<UdpPacket<B>> {
        let (header, body) = Ref::new_unaligned_from_prefix(bytes).ok()?;
        Some(UdpPacket { header, body })
    }

    pub fn get_src_port(&self) -> [u8; 2] {
        self.header.src_port
    }
}

impl<B: ByteSliceMut> UdpPacket<B> {
    pub fn with_src_port(&mut self, src_port: [u8; 2]) {
        self.header.src_port = src_port;
    }
}

Implementations

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

where B: ByteSlice, T: KnownLayout + Immutable + ?Sized,

pub fn new(bytes: B) -> Result<Ref<B, T>, CastError<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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = Ref::<_, ZSTy>::new(&b"UU"[..]); // ⚠ Compile Error!

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

where B: SplitByteSlice, T: KnownLayout + Immutable + ?Sized,

pub fn new_from_prefix(bytes: B) -> Result<(Ref<B, T>, B), CastError<B, T>>

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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = Ref::<_, ZSTy>::new_from_prefix(&b"UU"[..]); // ⚠ Compile Error!

pub fn new_from_suffix(bytes: B) -> Result<(B, Ref<B, T>), CastError<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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout)]
#[repr(C)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = Ref::<_, ZSTy>::new_from_suffix(&b"UU"[..]); // ⚠ Compile Error!

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

where B: ByteSlice, T: Unaligned + KnownLayout + Immutable + ?Sized,

pub fn new_unaligned(bytes: B) -> Result<Ref<B, T>, SizeError<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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout, Unaligned)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let f = Ref::<&[u8], ZSTy>::new_unaligned(&b"UU"[..]); // ⚠ Compile Error!

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

where B: SplitByteSlice, T: Unaligned + KnownLayout + Immutable + ?Sized,

pub fn new_unaligned_from_prefix( bytes: B ) -> Result<(Ref<B, T>, B), SizeError<B, T>>

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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout, Unaligned)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = Ref::<_, ZSTy>::new_unaligned_from_prefix(&b"UU"[..]); // ⚠ Compile Error!

pub fn new_unaligned_from_suffix( bytes: B ) -> Result<(B, Ref<B, T>), SizeError<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.

Compile-Time Assertions

This method cannot yet be used on unsized types whose dynamically-sized component is zero-sized. Attempting to use this method on such types results in a compile-time assertion error; e.g.:

use zerocopy::*;

#[derive(Immutable, KnownLayout, Unaligned)]
#[repr(C, packed)]
struct ZSTy {
    leading_sized: u16,
    trailing_dst: [()],
}

let _ = Ref::<_, ZSTy>::new_unaligned_from_suffix(&b"UU"[..]); // ⚠ Compile Error!

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

where B: 'a + IntoByteSlice<'a>, T: FromBytes + KnownLayout + Immutable + ?Sized,

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 + IntoByteSliceMut<'a>, T: FromBytes + IntoBytes + KnownLayout + ?Sized,

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

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

Writes the bytes of t and then forgets t.

Trait Implementations

impl<B: CloneableByteSlice + Clone, T: ?Sized> Clone for Ref<B, T>

fn clone(&self) -> Ref<B, T>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

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

where B: ByteSlice, T: FromBytes + Debug + KnownLayout + Immutable + ?Sized,

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 + KnownLayout + Immutable + ?Sized,

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 + IntoBytes + KnownLayout + Immutable + ?Sized,

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

Mutably dereferences the value.

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

where B: ByteSlice, T: FromBytes + Display + KnownLayout + Immutable + ?Sized,

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 + KnownLayout + Immutable + ?Sized,

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 + PartialOrd,

Restrict a value to a certain interval.

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

where B: ByteSlice, T: FromBytes + PartialEq + KnownLayout + Immutable + ?Sized,

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 !=. 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 + KnownLayout + Immutable + ?Sized,

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<B: CopyableByteSlice + Copy, T: ?Sized> Copy for Ref<B, T>

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

where B: ByteSlice, T: FromBytes + Eq + KnownLayout + Immutable + ?Sized,