Trait ptr_meta::Pointee

source · [−]

pub trait Pointee {
    type Metadata: Copy + Send + Sync + Ord + Hash + Unpin;
}

Expand description

Provides the pointer metadata type of any pointed-to type.

Pointer metadata

Raw pointer types and reference types in Rust can be thought of as made of two parts: a data pointer that contains the memory address of the value, and some additional metadata.

For statically-sized types (that implement Sized) as well as extern types, pointers are said to be “thin”. That is, their metadata is zero-sized and its type is ().

Pointers to dynamically-sized types are said to be “wide” or “fat”, and they have metadata that is not zero-sized:

For structs with a DST as the last field, the metadata of the struct is the metadata of the last field.
For the str type, the metadata is the length in bytes as a usize.
For slice types like [T], the metadata is the length in items as a usize.
For trait objects like dyn SomeTrait, the metadata is DynMetadata<Self> (e.g. DynMetadata<dyn SomeTrait>) which contains a pointer to the trait object’s vtable.

In the future, the Rust language may gain new kinds of types that have different pointer metadata.

The point of this trait is its associated Metadata type, which may be (), usize, or DynMetadata<_> as described above. It is automatically implemented for Sized types, slices, and strs. An implementation can be generated for structs with a trailing DST and trait objects using the derive macro and attribute macro respectively.

Usage

Raw pointers can be decomposed into the data address and metadata components with their to_raw_parts methods.

Alternatively, metadata alone can be extracted with the metadata function. A reference can be passed to metadata and be implicitly coerced to a pointer.

A (possibly wide) pointer can be put back together from its address and metadata with from_raw_parts or from_raw_parts_mut.