Struct BitPackedInts 

pub struct BitPackedInts { /* private fields */ }

Stores integers using only as many bits as the largest value needs.

Pass your values to pack() and we’ll figure out the optimal bit width automatically. Random access via get() is O(1).

Storage

Phase 3c: word storage has two shapes. Inline(Vec<u64>) is used for in-RAM builds (pack, from_raw_parts) so scans can iterate the &[u64] slice directly with no per-element decode. Mapped(Bytes) is used for mmap-backed loads (from_bytes_storage) so the column shares the underlying allocation without copying. Per-element access via word_at works for both; callers that want zero-decode iteration should use as_words_slice and fall back to word_at when it returns None.

Implementations

impl BitPackedInts

pub fn from_raw_parts(data: Vec<u64>, bits_per_value: u8, count: usize) -> Self

Reconstructs from pre-packed raw parts.

Used by section deserialization. The caller is responsible for ensuring the data is consistent (correct word count for the given bits and count).

pub fn from_bytes_storage(data: Bytes, bits_per_value: u8, count: usize) -> Self

Reconstructs from pre-encoded bytes (Phase 3c entry point).

The byte slice must be word_count * 8 bytes of little-endian u64 words. Used by the mmap path so a column can hold a slice of mapped memory without copying.

pub fn pack(values: &[u64]) -> Self

Packs a slice of u64 values using the minimum bits needed.

pub fn pack_with_bits(values: &[u64], bits_per_value: u8) -> Self

Packs values using a specified bit width.

Panics

Panics if any value doesn’t fit in the specified bit width.

pub fn unpack(&self) -> Vec<u64>

Unpacks all values back to u64.

pub fn get(&self, index: usize) -> Option<u64>

Gets a single value at the given index.

pub fn scan_eq(&self, target: u64) -> Vec<usize>

Returns the row offsets where the unpacked value equals target.

Hoists the WordStore discriminant check, the bits_per_value constants, and the values_per_word / mask computation out of the per-row loop. CodSpeed callgrind counts every retired instruction, so re-deriving these per row (as (0..len).filter(|i| get(*i) == ...) did) inflated the instruction count materially even though wall-time on real CPUs was unaffected.

pub fn len(&self) -> usize

Returns the number of values.

pub fn is_empty(&self) -> bool

Returns whether the encoding is empty.

pub fn bits_per_value(&self) -> u8

Returns the number of bits per value.

pub fn data_bytes(&self) -> Bytes

Returns the raw packed bytes.

Phase 3b/3c: when storage is Inline, we materialise an LE-encoded view; when storage is Mapped, we return the existing refcount. Callers that hold the result must accept either ownership shape.

pub fn word_count(&self) -> usize

Returns the number of u64 words backing this column.

pub fn as_words_slice(&self) -> Option<&[u64]>

Returns a direct &[u64] view when the column lives in RAM.

Some(slice) means the caller can iterate words without per-element decode. None means the column is mmap-backed; callers should fall back to Self::word_at (one safe LE decode per access).

pub fn word_at(&self, idx: usize) -> Option<u64>

Returns the word at idx, or None if out of range.

pub fn compression_ratio(&self) -> f64

Returns the compression ratio compared to storing full u64s.

pub fn bits_needed(value: u64) -> u8

Returns the number of bits needed to represent a value.

The result is always in 1..=64.

Panics

Cannot panic: the result of 64 - leading_zeros() is always in 1..=64, which fits u8.

pub fn to_bytes(&self) -> Result<Vec<u8>>

Serializes to bytes.

Errors

Returns Err if the value count exceeds u32::MAX.

pub fn from_bytes(bytes: &[u8]) -> Result<Self>

Deserializes from bytes.

Errors

Returns Err if the byte slice is too short or contains invalid data.

Trait Implementations

impl Clone for BitPackedInts

fn clone(&self) -> BitPackedInts

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for BitPackedInts

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

Formats the value using the given formatter.