Struct CardinalityPointer 

pub struct CardinalityPointer<T> { /* private fields */ }

8-byte pointer with log2(cardinality) packed into the high byte.

T: Sized so the pointer stays thin.

Implementations

impl<T> CardinalityPointer<T>

pub const SIGNATURE: AxisMask

Direction signature of CardinalityPointer<T>. Engages the K_content_prefix axis (log2-cardinality estimate stored at slot for size-class branching before deref).

pub unsafe fn from_raw(target: *const T, cardinality_hint: u64) -> Self

Construct from a raw pointer and a cardinality estimate. cardinality_hint is bucketed to its log2; values from 0 (single element) to 2^255 are encodable.

Runtime-checks that the address fits in the 56-bit envelope and panics on violation. For trusted hot paths where the caller has already verified the address fits (e.g. from a known-canonical allocator on x86-64 4-level paging), use Self::from_raw_unchecked to skip the check.

Safety

target must be a valid pointer to a T AND must remain valid for the lifetime of this pointer.

Panics

Panics if the high byte of target as u64 is non-zero (address exceeds the 56-bit envelope). The check runs in both debug and release builds.

pub unsafe fn from_raw_unchecked( target: *const T, cardinality_hint: u64, ) -> Self

Construct from a raw pointer and a cardinality estimate WITHOUT checking the address envelope. The high byte of the address is silently masked off via ADDR_MASK; if the caller violates the 56-bit envelope, the resulting pointer dereferences to the WRONG address.

Safety

In addition to the standard from_raw safety contract: caller asserts that (target as u64) & !ADDR_MASK == 0. On x86-64 with 4-level paging (the canonical configuration) this holds for any user-space pointer; on 5-level paging or with hardware MTE/TBI features that occupy the high byte it does NOT hold and using this constructor is undefined behaviour.

pub fn as_raw(&self) -> *const T

The address, with the cardinality byte masked off. This is the bit pattern that must be used for any deref or pointer comparison.

pub const fn log2_cardinality(&self) -> u8

Encoded log2(cardinality) value (0..=255).

pub fn cardinality(&self) -> u64

Reconstructed cardinality estimate. Caps at 2^63 (the max u64 representable in one 1 << k operation).

pub const fn raw(&self) -> u64

Raw u64 packing - useful for serialization or direct compare.

pub fn set_cardinality(&mut self, new_cardinality: u64)

Adjust the cardinality encoding in place; preserves the address bits.

pub fn size_tier(&self) -> SizeTier

Cardinality bucket for query-planner branching. Three coarse tiers covering the typical decision points.

Trait Implementations

impl<T> Clone for CardinalityPointer<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Copy for CardinalityPointer<T>

impl<T> Debug for CardinalityPointer<T>

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

Formats the value using the given formatter.

impl<T> Eq for CardinalityPointer<T>

impl<T> Hash for CardinalityPointer<T>

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

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> PartialEq for CardinalityPointer<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: Send> Send for CardinalityPointer<T>

impl<T: Sync> Sync for CardinalityPointer<T>