Struct Unalign

#[repr(C, packed(1))]
pub struct Unalign<T>(/* private fields */);

A type with no alignment requirement.

An Unalign wraps a T, removing any alignment requirement. Unalign<T> has the same size and bit validity as T, but not necessarily the same alignment or ABI. This is useful if a type with an alignment requirement needs to be read from a chunk of memory which provides no alignment guarantees.

Since Unalign has no alignment requirement, the inner T may not be properly aligned in memory. There are five ways to access the inner T:

• by value, using get or into_inner
• by reference inside of a callback, using update
• fallibly by reference, using try_deref or try_deref_mut; these can fail if the Unalign does not satisfy T’s alignment requirement at runtime
• unsafely by reference, using deref_unchecked or deref_mut_unchecked; it is the caller’s responsibility to ensure that the Unalign satisfies T’s alignment requirement
• (where T: Unaligned) infallibly by reference, using [Deref::deref] or [DerefMut::deref_mut]

Example

In this example, we need EthernetFrame to have no alignment requirement - and thus implement Unaligned. EtherType is #[repr(u16)] and so cannot implement Unaligned. We use Unalign to relax EtherType’s alignment requirement so that EthernetFrame has no alignment requirement and can implement Unaligned.

use zerocopy::*;

#[derive(TryFromBytes, KnownLayout, Immutable)]
#[repr(u16)]
enum EtherType {
    Ipv4 = 0x0800u16.to_be(),
    Arp = 0x0806u16.to_be(),
    Ipv6 = 0x86DDu16.to_be(),
    ...
}

#[derive(TryFromBytes, KnownLayout, Immutable, Unaligned)]
#[repr(C)]
struct EthernetFrame {
    src: Mac,
    dst: Mac,
    ethertype: Unalign<EtherType>,
    payload: [u8],
}

let bytes = &[
    ...
    0x86, 0xDD,            // EtherType
    0xDE, 0xAD, 0xBE, 0xEF // Payload
][..];

// PANICS: Guaranteed not to panic because `bytes` is of the right
// length, has the right contents, and `EthernetFrame` has no
// alignment requirement.
let packet = EthernetFrame::try_ref_from_bytes(&bytes).unwrap();

assert_eq!(packet.ethertype.get(), EtherType::Ipv6);
assert_eq!(packet.payload, [0xDE, 0xAD, 0xBE, 0xEF]);

Safety

Unalign<T> is guaranteed to have the same size and bit validity as T, and to have [UnsafeCell]s covering the same byte ranges as T. Unalign<T> is guaranteed to have alignment 1.

Implementations

impl<T> Unalign<T>

pub const fn new(val: T) -> Unalign<T>

Constructs a new Unalign.

pub const fn into_inner(self) -> T

Consumes self, returning the inner T.

pub fn try_deref(&self) -> Result<&T, AlignmentError<&Self, T>>

Attempts to return a reference to the wrapped T, failing if self is not properly aligned.

If self does not satisfy align_of::<T>(), then try_deref returns Err.

If T: Unaligned, then Unalign<T> implements [Deref], and callers may prefer [Deref::deref], which is infallible.

pub fn try_deref_mut(&mut self) -> Result<&mut T, AlignmentError<&mut Self, T>>

Attempts to return a mutable reference to the wrapped T, failing if self is not properly aligned.

If self does not satisfy align_of::<T>(), then try_deref returns Err.

If T: Unaligned, then Unalign<T> implements [DerefMut], and callers may prefer [DerefMut::deref_mut], which is infallible.

pub const unsafe fn deref_unchecked(&self) -> &T

Returns a reference to the wrapped T without checking alignment.

If T: Unaligned, then Unalign<T> implements[ Deref], and callers may prefer [Deref::deref], which is safe.

Safety

The caller must guarantee that self satisfies align_of::<T>().

pub unsafe fn deref_mut_unchecked(&mut self) -> &mut T

Returns a mutable reference to the wrapped T without checking alignment.

If T: Unaligned, then Unalign<T> implements[ DerefMut], and callers may prefer [DerefMut::deref_mut], which is safe.

Safety

The caller must guarantee that self satisfies align_of::<T>().

pub const fn get_ptr(&self) -> *const T

Gets an unaligned raw pointer to the inner T.

Safety

The returned raw pointer is not necessarily aligned to align_of::<T>(). Most functions which operate on raw pointers require those pointers to be aligned, so calling those functions with the result of get_ptr will result in undefined behavior if alignment is not guaranteed using some out-of-band mechanism. In general, the only functions which are safe to call with this pointer are those which are explicitly documented as being sound to use with an unaligned pointer, such as read_unaligned.

Even if the caller is permitted to mutate self (e.g. they have ownership or a mutable borrow), it is not guaranteed to be sound to write through the returned pointer. If writing is required, prefer get_mut_ptr instead.

pub fn get_mut_ptr(&mut self) -> *mut T

Gets an unaligned mutable raw pointer to the inner T.

Safety

The returned raw pointer is not necessarily aligned to align_of::<T>(). Most functions which operate on raw pointers require those pointers to be aligned, so calling those functions with the result of get_ptr will result in undefined behavior if alignment is not guaranteed using some out-of-band mechanism. In general, the only functions which are safe to call with this pointer are those which are explicitly documented as being sound to use with an unaligned pointer, such as read_unaligned.

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

Sets the inner T, dropping the previous value.

pub fn update<O, F: FnOnce(&mut T) -> O>(&mut self, f: F) -> O

Updates the inner T by calling a function on it.

If T: Unaligned, then Unalign<T> implements [DerefMut], and that impl should be preferred over this method when performing updates, as it will usually be faster and more ergonomic.

For large types, this method may be expensive, as it requires copying 2 * size_of::<T>() bytes. [1]

[1] Since the inner T may not be aligned, it would not be sound to invoke f on it directly. Instead, update moves it into a properly-aligned location in the local stack frame, calls f on it, and then moves it back to its original location in self.

impl<T: Copy> Unalign<T>

pub fn get(&self) -> T

Gets a copy of the inner T.

Trait Implementations

impl<T: Copy> Clone for Unalign<T>

fn clone(&self) -> Unalign<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Unaligned + Debug> Debug for Unalign<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default> Default for Unalign<T>

fn default() -> Unalign<T>

Returns the “default value” for a type.

impl<T: Unaligned> Deref for Unalign<T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: Unaligned> DerefMut for Unalign<T>

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

Mutably dereferences the value.

impl<T: Unaligned + Display> Display for Unalign<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> FromBytes for Unalign<T>

where T: FromBytes,

fn ref_from_bytes(source: &[u8]) -> Result<&Self, CastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Interprets the given source as a &Self.

fn ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), CastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Interprets the prefix of the given source as a &Self without copying.

fn ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), CastError<&[u8], Self>>

where Self: Immutable + KnownLayout,

Interprets the suffix of the given bytes as a &Self.

fn mut_from_bytes( source: &mut [u8], ) -> Result<&mut Self, CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the given source as a &mut Self.

fn mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the prefix of the given source as a &mut Self without copying.

fn mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), CastError<&mut [u8], Self>>

where Self: IntoBytes + KnownLayout,

Interprets the suffix of the given source as a &mut Self without copying.

fn read_from_bytes(source: &[u8]) -> Result<Self, SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the given source.

fn read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the prefix of the given source.

fn read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), SizeError<&[u8], Self>>

where Self: Sized,

Reads a copy of Self from the suffix of the given source.

impl<T> FromZeros for Unalign<T>

where T: FromZeros,

fn zero(&mut self)

Overwrites self with zeros.

fn new_zeroed() -> Self

where Self: Sized,

Creates an instance of Self from zeroed bytes.

impl<T: Unaligned + Hash> Hash for Unalign<T>

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given [Hasher].

impl<T> IntoBytes for Unalign<T>

where T: IntoBytes,

fn as_bytes(&self) -> &[u8]

where Self: Immutable,

Gets the bytes of this value.

fn as_mut_bytes(&mut self) -> &mut [u8]

where Self: FromBytes,

Gets the bytes of this value mutably.

fn write_to(&self, dst: &mut [u8]) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to dst.

fn write_to_prefix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the prefix of dst.

fn write_to_suffix( &self, dst: &mut [u8], ) -> Result<(), SizeError<&Self, &mut [u8]>>

where Self: Immutable,

Writes a copy of self to the suffix of dst.

impl<T> KnownLayout for Unalign<T>

type PointerMetadata = ()

The type of metadata stored in a pointer to Self.

impl<T: Unaligned + Ord> Ord for Unalign<T>

fn cmp(&self, other: &Unalign<T>) -> 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: Unaligned + PartialEq> PartialEq for Unalign<T>

fn eq(&self, other: &Unalign<T>) -> 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: Unaligned + PartialOrd> PartialOrd for Unalign<T>

fn partial_cmp(&self, other: &Unalign<T>) -> 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<T> TryFromBytes for Unalign<T>

where T: TryFromBytes,

fn try_ref_from_bytes(source: &[u8]) -> Result<&Self, TryCastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Attempts to interpret the given source as a &Self.

fn try_ref_from_prefix( source: &[u8], ) -> Result<(&Self, &[u8]), TryCastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Attempts to interpret the prefix of the given source as a &Self.

fn try_ref_from_suffix( source: &[u8], ) -> Result<(&[u8], &Self), TryCastError<&[u8], Self>>

where Self: KnownLayout + Immutable,

Attempts to interpret the suffix of the given source as a &Self.

fn try_mut_from_bytes( bytes: &mut [u8], ) -> Result<&mut Self, TryCastError<&mut [u8], Self>>

where Self: KnownLayout,

Attempts to interpret the given source as a &mut Self without copying.

fn try_mut_from_prefix( source: &mut [u8], ) -> Result<(&mut Self, &mut [u8]), TryCastError<&mut [u8], Self>>

where Self: KnownLayout,

Attempts to interpret the prefix of the given source as a &mut Self.

fn try_mut_from_suffix( source: &mut [u8], ) -> Result<(&mut [u8], &mut Self), TryCastError<&mut [u8], Self>>

where Self: KnownLayout,

Attempts to interpret the suffix of the given source as a &mut Self.

fn try_read_from_bytes(source: &[u8]) -> Result<Self, TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read the given source as a Self.

fn try_read_from_prefix( source: &[u8], ) -> Result<(Self, &[u8]), TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read a Self from the prefix of the given source.

fn try_read_from_suffix( source: &[u8], ) -> Result<(&[u8], Self), TryReadError<&[u8], Self>>

where Self: Sized,

Attempts to read a Self from the suffix of the given source.

impl<T: Copy> Copy for Unalign<T>

impl<T: Unaligned + Eq> Eq for Unalign<T>

impl<T> Immutable for Unalign<T>

where T: Immutable,

impl<T> Unaligned for Unalign<T>