Struct zerocopy::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

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) -> Option<&T>

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

If self does not satisfy mem::align_of::<T>(), then it is unsound to return a reference to the wrapped T, and try_deref returns None.

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

pub fn try_deref_mut(&mut self) -> Option<&mut T>

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

If self does not satisfy mem::align_of::<T>(), then it is unsound to return a reference to the wrapped T, and try_deref_mut returns None.

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

If self does not satisfy mem::align_of::<T>(), then self.deref_unchecked() may cause undefined behavior.

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

If self does not satisfy mem::align_of::<T>(), then self.deref_mut_unchecked() may cause undefined behavior.

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 be 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 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 be 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: AsBytes> AsBytes for Unalign<T>

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

Gets the bytes of this value.

fn write_to(&self, bytes: &mut [u8]) -> Option<()>

Writes a copy of self to bytes.

fn write_to_prefix(&self, bytes: &mut [u8]) -> Option<()>

Writes a copy of self to the prefix of bytes.

fn write_to_suffix(&self, bytes: &mut [u8]) -> Option<()>

Writes a copy of self to the suffix of bytes.

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> FromBytes for Unalign<T>

fn ref_from(bytes: &[u8]) -> Option<&Self>

where Self: Sized,

Interprets the given bytes as a &Self without copying.

fn ref_from_prefix(bytes: &[u8]) -> Option<&Self>

where Self: Sized,

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

fn ref_from_suffix(bytes: &[u8]) -> Option<&Self>

where Self: Sized,

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

fn slice_from(bytes: &[u8]) -> Option<&[Self]>

where Self: Sized,

Interprets the given bytes as a &[Self] without copying.

fn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>

where Self: Sized,

Interprets the prefix of the given bytes as a &[Self] with length equal to count without copying.

fn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>

where Self: Sized,

Interprets the suffix of the given bytes as a &[Self] with length equal to count without copying.

fn read_from(bytes: &[u8]) -> Option<Self>

where Self: Sized,

Reads a copy of Self from bytes.

fn read_from_prefix(bytes: &[u8]) -> Option<Self>

where Self: Sized,

Reads a copy of Self from the prefix of bytes.

fn read_from_suffix(bytes: &[u8]) -> Option<Self>

where Self: Sized,

Reads a copy of Self from the suffix of bytes.

impl<T: FromZeroes> FromZeroes for Unalign<T>

fn zero(&mut self)

Overwrites self with zeroes.

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

Restrict a value to a certain interval.

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

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

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<T: Copy> Copy for Unalign<T>

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

impl<T> Unaligned for Unalign<T>