#[repr(C, packed(1))]pub struct Unalign<T>(/* private fields */);
Expand description
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
orinto_inner
- by reference inside of a callback, using
update
- fallibly by reference, using
try_deref
ortry_deref_mut
; these can fail if theUnalign
does not satisfyT
’s alignment requirement at runtime - unsafely by reference, using
deref_unchecked
orderef_mut_unchecked
; it is the caller’s responsibility to ensure that theUnalign
satisfiesT
’s alignment requirement - (where
T: Unaligned
) infallibly by reference, usingDeref::deref
orDerefMut::deref_mut
Implementations§
source§impl<T> Unalign<T>
impl<T> Unalign<T>
sourcepub const fn into_inner(self) -> T
pub const fn into_inner(self) -> T
Consumes self
, returning the inner T
.
sourcepub fn try_deref(&self) -> Option<&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.
sourcepub fn try_deref_mut(&mut self) -> Option<&mut T>
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.
sourcepub const unsafe fn deref_unchecked(&self) -> &T
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.
sourcepub unsafe fn deref_mut_unchecked(&mut self) -> &mut 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
If self
does not satisfy mem::align_of::<T>()
, then
self.deref_mut_unchecked()
may cause undefined behavior.
sourcepub const fn get_ptr(&self) -> *const 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 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
.
sourcepub fn get_mut_ptr(&mut self) -> *mut T
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
.
sourcepub fn update<O, F: FnOnce(&mut T) -> O>(&mut self, f: F) -> O
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
.
Trait Implementations§
source§impl<T> AsBytes for Unalign<T>where
T: AsBytes,
impl<T> AsBytes for Unalign<T>where
T: AsBytes,
source§impl<T> FromBytes for Unalign<T>where
T: FromBytes,
impl<T> FromBytes for Unalign<T>where
T: FromBytes,
source§fn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>where
Self: Sized,
fn slice_from_prefix(bytes: &[u8], count: usize) -> Option<(&[Self], &[u8])>where
Self: Sized,
bytes
as a &[Self]
with length
equal to count
without copying. Read moresource§fn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>where
Self: Sized,
fn slice_from_suffix(bytes: &[u8], count: usize) -> Option<(&[u8], &[Self])>where
Self: Sized,
bytes
as a &[Self]
with length
equal to count
without copying. Read moresource§impl<T> FromZeroes for Unalign<T>where
T: FromZeroes,
impl<T> FromZeroes for Unalign<T>where
T: FromZeroes,
source§impl<T: Unaligned + Ord> Ord for Unalign<T>
impl<T: Unaligned + Ord> Ord for Unalign<T>
1.21.0 · source§fn max(self, other: Self) -> Selfwhere
Self: Sized,
fn max(self, other: Self) -> Selfwhere
Self: Sized,
source§impl<T: Unaligned + PartialEq> PartialEq for Unalign<T>
impl<T: Unaligned + PartialEq> PartialEq for Unalign<T>
source§impl<T: Unaligned + PartialOrd> PartialOrd for Unalign<T>
impl<T: Unaligned + PartialOrd> PartialOrd for Unalign<T>
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl<T: Copy> Copy for Unalign<T>
impl<T: Unaligned + Eq> Eq for Unalign<T>
impl<T> Unaligned for Unalign<T>
Auto Trait Implementations§
impl<T> Freeze for Unalign<T>where
T: Freeze,
impl<T> RefUnwindSafe for Unalign<T>where
T: RefUnwindSafe,
impl<T> Send for Unalign<T>where
T: Send,
impl<T> Sync for Unalign<T>where
T: Sync,
impl<T> Unpin for Unalign<T>where
T: Unpin,
impl<T> UnwindSafe for Unalign<T>where
T: UnwindSafe,
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Copy,
impl<T> CloneToUninit for Twhere
T: Copy,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)