Struct fat_type::Fat

#[repr(C)]
pub struct Fat<T: ?Sized, U: ?Sized = Erased> { /* private fields */ }

A type which combines a value with the metadata used to construct references to it.

A value of the type Fat<T: ?Sized, U: Unsize<T>>, created by new, supports pointer-sized “thin” references &Fat<T> (via erase_ref) and &mut Fat<T> (via erase_mut), even when T is not Thin, such as in the case of slices or trait objects.

Terminology

• The value of type T is referred to as the unsized referent.
• The value of type U is referred to as the sized referent.
• Fat<T> references are produced from Fat<T, U> references through erasure, where Erased replaces U. The original U is referred to as the un-erased type.

Auto-Deref

Fat<T> is Deref and DerefMut as T. All operations are provided as associated functions to prevent name collisions. This means that you use references to Fat<T> as-if they were to T.

Safety

• Incoherent tyes can be named but cannot be constructed by safe code because new is only provided when U: Unsize<T>.
• The ability to incoherently mutate metadata is prevented by Erased, which is a fully-opaque extern type.
• There is no constructor to create a bare Fat<T>. As such, the type can only exist behind a reference, which can only safely be created by erase_ref and erase_mut.

Example

// References to wrapped trait objects are smaller than the bare references.
assert!(mem::size_of::<&Fat<dyn Debug>>() < mem::size_of::<&dyn Debug>());

// References to wrapped trait objects are, in fact, pointer sized.
assert!(mem::size_of::<&Fat<dyn Debug>>() == mem::size_of::<&()>());

See Also

• new – To create a Fat value.
• erase_ref, erase_mut – To obtain a thin reference from a Fat reference.

Implementations

impl<T: ?Sized, U: Unsize<T>> Fat<T, U>

pub fn new(value: U) -> Self

Constructs a new Fat value with metadata from unsizing value as a T.

Example

let fat = Fat::<dyn Debug, u8>::new(42);
let thin: &Fat<dyn Debug> = Fat::erase_ref(&fat);
assert_eq!(mem::size_of_val(&thin), mem::size_of::<&()>());

dbg!(thin); // 42

impl<T: ?Sized, U> Fat<T, U>

pub fn into_inner(fat: Self) -> U

Extracts the sized referent, discarding the associated metadata.

pub fn inner_ref(fat: &Self) -> &U

Obtains an immutable reference to the sized referent.

pub fn inner_mut(fat: &mut Self) -> &mut U

Obtains a mutable reference to the sized referent.

impl<T: ?Sized> Fat<T>

pub unsafe fn container_of(referent: *const T) -> NonNull<Self>

Obtains a pointer to the Fat<T> containing the specified unsized referent.

Safety

referent must be the unsized referent of some Fat<T>, such as the reference obtained from deref.

Safety Considerations

core::ptr::NonNull provides methods that treat the contained pointer as-if it were a pointer to mutable data. Use of these operations may lead to undefined behavior.

Strict Pointer Provenance

The provenance of the returned pointer is inherited from the argument.

impl<T: ?Sized, U: ?Sized> Fat<T, U>

pub fn erase_ref(fat: &Self) -> &Fat<T>

Obtains a thin immutable reference by erasing the type of the sized referent.

pub fn erase_mut(fat: &mut Self) -> &mut Fat<T>

Obtains a thin mutable reference by erasing the type of the sized referent.

pub fn data_addr(fat: &Self) -> NonNull<()>

Returns a thin pointer to the sized referent, suitable for use with core::ptr::from_raw_parts.

Safety Considerations

core::ptr::NonNull provides methods that treat the contained pointer as-if it were a pointer to mutable data. Use of these operations may lead to undefined behavior. Consider using Fat::data_addr_mut instead, if possible.

Strict Pointer Provenance

The provenance of the returned pointer is inherited from the argument.

pub fn data_addr_mut(fat: &mut Self) -> NonNull<()>

Returns a thin pointer to the sized referent, suitable for use with core::ptr::from_raw_parts_mut.

Strict Pointer Provenance

The provenance of the returned pointer is inherited from the argument.

pub fn metadata(fat: &Self) -> &<T as Pointee>::Metadata

Obtains an immutable reference to the metadata used to construct references to the unsized referent.

pub fn layout_of(fat: &Self) -> (Layout, usize)

Obtains layout information for the specified value.

See Fat::layout_for.

Example

let fat = Fat::<dyn Debug, u32>::new(42);
let thin: &Fat<dyn Debug> = Fat::erase_ref(&fat);

// Despite type erasure, we can obtain the original layout.
assert_eq!(Fat::layout_of(thin).0, Layout::for_value(&fat));

pub unsafe fn layout_for(metadata: &<T as Pointee>::Metadata) -> (Layout, usize)

Obtains layout information for a Fat<T, U> having the provided pointer metadata.

Returns

• The allocation Layout of a Fat<T, U> with the specified metadata.
• The corresponding pointer offset of the unsized referent.

The returned layout information is correct in the sense that unsafe code may rely on it being the actual layout of a Fat<T, U> with the specified metadata.

Safety

The provided metadata must be the result of the unsizing operation T as U.

Trait Implementations

impl<T: ?Sized, U: ?Sized> AsMut<Fat<T, Erased>> for Fat<T, U>

fn as_mut(&mut self) -> &mut Fat<T>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ?Sized, U: ?Sized> AsMut<T> for Fat<T, U>

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

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T: ?Sized, U: ?Sized> AsRef<Fat<T, Erased>> for Fat<T, U>

fn as_ref(&self) -> &Fat<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: ?Sized, U: ?Sized> AsRef<T> for Fat<T, U>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: ?Sized, U> Borrow<Fat<T, Erased>> for Fat<T, U>

fn borrow(&self) -> &Fat<T>

Immutably borrows from an owned value.

impl<T: ?Sized, U: ?Sized> Borrow<T> for Fat<T, U>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: ?Sized, U> BorrowMut<Fat<T, Erased>> for Fat<T, U>

fn borrow_mut(&mut self) -> &mut Fat<T>

Mutably borrows from an owned value.

impl<T: ?Sized, U: ?Sized> BorrowMut<T> for Fat<T, U>

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

Mutably borrows from an owned value.

impl<T: ?Sized, U: Unsize<T> + Clone> Clone for Fat<T, U>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: ?Sized, U: ?Sized> Debug for Fat<T, U>where
    <T as Pointee>::Metadata: Debug,

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

Formats the value using the given formatter.

impl<T: ?Sized, U: Default + Unsize<T>> Default for Fat<T, U>

fn default() -> Self

Returns the “default value” for a type.

impl<T: ?Sized, U: ?Sized> Deref for Fat<T, U>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &T

Dereferences the value.

impl<T: ?Sized, U: ?Sized> DerefMut for Fat<T, U>

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

Mutably dereferences the value.

impl<T: Display + ?Sized, U: ?Sized> Display for Fat<T, U>

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

Formats the value using the given formatter.

impl<T: ?Sized, U: Unsize<T>> From<U> for Fat<T, U>

fn from(value: U) -> Self

Converts to this type from the input type.

impl<T: Hash + ?Sized, U: ?Sized> Hash for Fat<T, U>

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

Feeds this value into the given Hasher.

impl<T: Index<Idx> + ?Sized, U: ?Sized, Idx> Index<Idx> for Fat<T, U>

type Output = <T as Index<Idx>>::Output

The returned type after indexing.

fn index(&self, index: Idx) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T: IndexMut<Idx> + ?Sized, U: ?Sized, Idx> IndexMut<Idx> for Fat<T, U>

fn index_mut(&mut self, index: Idx) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl<'a, T: ?Sized, U: ?Sized> IntoIterator for &'a Fat<T, U>where
    &'a T: IntoIterator,

type Item = <&'a T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T: ?Sized, U: ?Sized> IntoIterator for &'a mut Fat<T, U>where
    &'a mut T: IntoIterator,

type Item = <&'a mut T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a mut T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: Ord + ?Sized, U: ?Sized> Ord for Fat<T, U>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

impl<T: PartialEq + ?Sized, U: ?Sized, V: ?Sized> PartialEq<Fat<T, V>> for Fat<T, U>

fn eq(&self, other: &Fat<T, V>) -> 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: PartialEq + ?Sized, U: ?Sized> PartialEq<T> for Fat<T, U>

fn eq(&self, other: &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: PartialOrd + ?Sized, U: ?Sized, V: ?Sized> PartialOrd<Fat<T, V>> for Fat<T, U>

fn partial_cmp(&self, other: &Fat<T, V>) -> 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: PartialOrd + ?Sized, U: ?Sized> PartialOrd<T> for Fat<T, U>

fn partial_cmp(&self, other: &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: ?Sized, U: Unsize<T> + Copy> Copy for Fat<T, U>

impl<T: Eq + ?Sized, U: ?Sized> Eq for Fat<T, U>