Struct Ref

pub struct Ref<B, T: ?Sized>(B, PhantomData<T>);

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::*;

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct UdpHeader {
    src_port: [u8; 2],
    dst_port: [u8; 2],
    length: [u8; 2],
    checksum: [u8; 2],
}

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C, packed)]
struct UdpPacket {
    header: UdpHeader,
    body: [u8],
}

impl UdpPacket {
    pub fn parse<B: ByteSlice>(bytes: B) -> Option<Ref<B, UdpPacket>> {
        Ref::from_bytes(bytes).ok()
    }
}

Tuple Fields

0: B

1: PhantomData<T>

Implementations

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

pub(crate) unsafe fn new_unchecked(bytes: B) -> Ref<B, T>

Constructs a new Ref.

Safety

bytes dereferences (via deref, deref_mut, and into) to a byte slice which is aligned to T’s alignment and whose size is a valid size for T.

impl<B: ByteSlice, T: ?Sized> Ref<B, T>

pub(crate) unsafe fn as_byte_slice(&self) -> &impl ByteSlice

Access the byte slice as a ByteSlice.

Safety

The caller promises not to call methods on the returned ByteSlice other than ByteSlice methods (for example, via Any::downcast_ref).

as_byte_slice promises to return a ByteSlice whose referent is validly-aligned for T and has a valid size for T.

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

pub(crate) unsafe fn as_byte_slice_mut(&mut self) -> &mut impl ByteSliceMut

Access the byte slice as a ByteSliceMut.

Safety

The caller promises not to call methods on the returned ByteSliceMut other than ByteSliceMut methods (for example, via Any::downcast_mut).

as_byte_slice promises to return a ByteSlice whose referent is validly-aligned for T and has a valid size for T.

impl<'a, B: IntoByteSlice<'a>, T: ?Sized> Ref<B, T>

pub(crate) unsafe fn into_byte_slice(self) -> impl IntoByteSlice<'a>

Access the byte slice as an IntoByteSlice.

Safety

The caller promises not to call methods on the returned IntoByteSlice other than IntoByteSlice methods (for example, via Any::downcast_ref).

as_byte_slice promises to return a ByteSlice whose referent is validly-aligned for T and has a valid size for T.

impl<'a, B: IntoByteSliceMut<'a>, T: ?Sized> Ref<B, T>

pub(crate) unsafe fn into_byte_slice_mut(self) -> impl IntoByteSliceMut<'a>

Access the byte slice as an IntoByteSliceMut.

Safety

The caller promises not to call methods on the returned IntoByteSliceMut other than IntoByteSliceMut methods (for example, via Any::downcast_mut).

as_byte_slice promises to return a ByteSlice whose referent is validly-aligned for T and has a valid size for T.

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

where B: ByteSlice,

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

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

where B: SplitByteSlice,

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

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

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

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

pub fn from_bytes(source: B) -> Result<Ref<B, T>, CastError<B, T>>

Constructs a Ref from a byte slice.

If the length of source is not a valid size of T, or if source is not appropriately aligned for T, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

T may be a sized type, a slice, or a slice DST.

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>::from_bytes(&b"UU"[..]); // ⚠ Compile Error!

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

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

pub fn from_prefix(source: B) -> Result<(Ref<B, T>, B), CastError<B, T>>

Constructs a Ref from the prefix of a byte slice.

This method computes the largest possible size of T that can fit in the leading bytes of source, then attempts to return both a Ref to those bytes, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

T may be a sized type, a slice, or a slice DST.

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>::from_prefix(&b"UU"[..]); // ⚠ Compile Error!

pub fn from_suffix(source: B) -> Result<(B, Ref<B, T>), CastError<B, T>>

Constructs a Ref from the suffix of a byte slice.

This method computes the largest possible size of T that can fit in the trailing bytes of source, then attempts to return both a Ref to those bytes, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

T may be a sized type, a slice, or a slice DST.

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>::from_suffix(&b"UU"[..]); // ⚠ Compile Error!

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

where B: ByteSlice, T: KnownLayout<PointerMetadata = usize> + Immutable + ?Sized,

pub fn from_bytes_with_elems( source: B, count: usize, ) -> Result<Ref<B, T>, CastError<B, T>>

Constructs a Ref from the given bytes with DST length equal to count without copying.

This method attempts to return a Ref to the prefix of source interpreted as a T with count trailing elements, and a reference to the remaining bytes. If the length of source is not equal to the size of Self with count elements, or if source is not appropriately aligned, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

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>::from_bytes_with_elems(&b"UU"[..], 42); // ⚠ Compile Error!

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

where B: SplitByteSlice, T: KnownLayout<PointerMetadata = usize> + Immutable + ?Sized,

pub fn from_prefix_with_elems( source: B, count: usize, ) -> Result<(Ref<B, T>, B), CastError<B, T>>

Constructs a Ref from the prefix of the given bytes with DST length equal to count without copying.

This method attempts to return a Ref to the prefix of source interpreted as a T with count trailing elements, and a reference to the remaining bytes. If there are insufficient bytes, or if source is not appropriately aligned, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

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>::from_prefix_with_elems(&b"UU"[..], 42); // ⚠ Compile Error!

pub fn from_suffix_with_elems( source: B, count: usize, ) -> Result<(B, Ref<B, T>), CastError<B, T>>

Constructs a Ref from the suffix of the given bytes with DST length equal to count without copying.

This method attempts to return a Ref to the suffix of source interpreted as a T with count trailing elements, and a reference to the preceding bytes. If there are insufficient bytes, or if that suffix of source is not appropriately aligned, this returns Err. If T: Unaligned, you can infallibly discard the alignment error.

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>::from_suffix_with_elems(&b"UU"[..], 42); // ⚠ Compile Error!

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

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

pub fn into_ref(r: Self) -> &'a T

Converts this Ref into a reference.

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

Note: this is an associated function, which means that you have to call it as Ref::into_ref(r) instead of r.into_ref(). This is so that there is no conflict with a method on the inner type.

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

where B: 'a + IntoByteSliceMut<'a>, T: FromBytes + IntoBytes + KnownLayout + ?Sized,

pub fn into_mut(r: Self) -> &'a mut T

Converts this Ref into a mutable reference.

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

Note: this is an associated function, which means that you have to call it as Ref::into_mut(r) instead of r.into_mut(). This is so that there is no conflict with a method on the inner type.

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

where B: ByteSlice, T: ?Sized,

pub fn bytes(r: &Self) -> &[u8]

Gets the underlying bytes.

Note: this is an associated function, which means that you have to call it as Ref::bytes(r) instead of r.bytes(). This is so that there is no conflict with a method on the inner type.

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

where B: ByteSliceMut, T: ?Sized,

pub fn bytes_mut(r: &mut Self) -> &mut [u8]

Gets the underlying bytes mutably.

Note: this is an associated function, which means that you have to call it as Ref::bytes_mut(r) instead of r.bytes_mut(). This is so that there is no conflict with a method on the inner type.

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

where B: ByteSlice, T: FromBytes,

pub fn read(r: &Self) -> T

Reads a copy of T.

Note: this is an associated function, which means that you have to call it as Ref::read(r) instead of r.read(). This is so that there is no conflict with a method on the inner type.

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

where B: ByteSliceMut, T: IntoBytes,

pub fn write(r: &mut Self, t: T)

Writes the bytes of t and then forgets t.

Note: this is an associated function, which means that you have to call it as Ref::write(r, t) instead of r.write(t). This is so that there is no conflict with a method on the inner type.

Trait Implementations

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

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

Returns a duplicate 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,

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

Tests for self and other values to be equal, and is used by ==.

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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,