Struct PackedPointer 

pub struct PackedPointer<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool = true> { /* private fields */ }

A pointer wrapper that allows storing a small amount of data in the alignment bits of the pointer.

The number of bits available for packing (DATA_BITS) must be less than or equal to the number of trailing zero bits in the alignment of T.

PackedPointer enforces compile-time validation of the alignment constraints using const assertions, and runtime debug assertions to verify pointer alignment and data limits.

If CHECK_ALIGNMENT is set to false, the compile-time alignment check is bypassed. This can be useful when working with types whose alignment cannot be validated at compile-time.

This implementation preserves pointer provenance by using Rust’s strict provenance methods (addr, with_addr, map_addr).

Implementations

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

pub fn new(ptr: *mut T, data: usize) -> Self

Creates a new PackedPointer from a pointer and data.

Panics

Panics in debug builds if the pointer is not aligned to the required boundary, or if the data exceeds the allowed number of bits.

pub const fn null() -> Self

Creates a new, empty packed pointer.

pub fn from_ptr(ptr: *mut T) -> Self

Creates a PackedPointer from a pointer with zeroed data bits.

pub const fn from_data(data: usize) -> Self

Creates a PackedPointer with a null pointer and specified data.

Panics

Panics if the data exceeds the allowed number of bits.

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

Returns the unpacked pointer, preserving its original provenance.

pub fn data(&self) -> usize

Returns the unpacked data.

pub fn set_ptr(&mut self, ptr: *mut T)

Sets the pointer, preserving the currently packed data.

pub fn set_data(&mut self, data: usize)

Sets the data, preserving the currently packed pointer and its provenance.

pub fn reset(&mut self)

Resets the packed pointer to null with zero data.

pub fn is_null(&self) -> bool

Returns true if the unpacked pointer is null.

Trait Implementations

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> Clone for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> Debug for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

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

Formats the value using the given formatter.

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> Default for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn default() -> Self

Returns the “default value” for a type.

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> From<*mut T> for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn from(ptr: *mut T) -> Self

Converts to this type from the input type.

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> PartialEq<*const T> for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn eq(&self, other: &*const 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, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> PartialEq<*mut T> for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn eq(&self, other: &*mut 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, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> PartialEq for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

fn eq(&self, other: &Self) -> 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, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> Copy for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>

impl<T, const DATA_BITS: usize, const CHECK_ALIGNMENT: bool> Eq for PackedPointer<T, DATA_BITS, CHECK_ALIGNMENT>