Struct IntVecBuilder

pub struct IntVecBuilder<'a, E: Endianness> { /* private fields */ }

A builder for creating an IntVec from a slice (&[u64]).

This builder is obtained by calling IntVec::builder. It provides a fluent interface for setting parameters like the sampling rate k and the compression CodecSpec.

Because it operates on a slice, it can automatically select the best codec parameters by analyzing the data first. This is the recommended way to construct an IntVec when all data is available in memory.

Implementations

impl<'a, E: Endianness> IntVecBuilder<'a, E>

pub fn k(self, k: usize) -> Self

Sets the sampling rate k for DSI-based codecs.

The sampling rate determines how frequently a sample of the bitstream’s position is stored. A smaller k leads to faster random access but increases memory overhead. A larger k reduces memory usage but slows down access.

The value must be greater than 0. This parameter is ignored for FixedLength encoding, as random access is already $O(1)$.

Arguments

• k: The sampling rate.

pub fn codec(self, codec_spec: CodecSpec) -> Self

Sets the codec specification for compression.

This determines which compression algorithm will be used. See CodecSpec for available options. It can be a specific codec (e.g., Gamma) or a request for automatic selection (Auto).

Arguments

• codec_spec: The desired codec specification.

Example

use compressed_intvec::prelude::*;

let data: &[u64] = &[1, 2, 3, 4, 5];
let intvec = LEIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .build()
    .unwrap();

assert_eq!(intvec.encoding(), Encoding::Dsi(dsi_bitstream::prelude::Codes::Gamma));

pub fn build(self) -> Result<IntVec<E>, IntVecError>

where BufBitWriter<E, MemWordWriterVec<u64, Vec<u64>>>: BitWrite<E, Error = Infallible> + CodesWrite<E>,

Builds the IntVec, consuming the builder.

This method performs the main compression logic. It resolves the CodecSpec, automatically selecting parameters if requested (e.g., for CodecSpec::Auto or CodecSpec::Rice { log2_b: None }). It then encodes the input data and builds the final IntVec structure.

Returns

A Result containing the constructed IntVec on success, or an IntVecError if there’s a problem, such as:

• k=0 for a DSI-based codec.
• A value in the input data does not fit within the specified number of bits for FixedLength encoding.

Examples

Automatic Codec Selection

Using CodecSpec::Auto (the default) allows the builder to choose an optimal codec based on a sample of the data.

use compressed_intvec::prelude::*;

let data: Vec<u64> = (0..100).map(|x| x * x).collect();

// Build with default settings (auto codec, k=32).
let intvec = LEIntVec::builder(&data).build().unwrap();

assert_eq!(intvec.len(), 100);
assert_eq!(intvec.get(10), Some(100)); // 10*10

Specifying a Codec

You can explicitly set the codec and sampling rate.

use compressed_intvec::prelude::*;

let data: &[u64] = &[1, 2, 3, 4, 5];

// Use Gamma coding with a small sampling rate.
let intvec = LEIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .k(2)
    .build()
    .unwrap();

assert_eq!(intvec.get(4), Some(5));
assert_eq!(intvec.get_sampling_rate(), Some(2));

Using Fixed-Length Encoding

For data that is bounded, FixedLength can be very efficient.

use compressed_intvec::prelude::*;

// All values are less than 256, so they fit in 8 bits.
let data: &[u64] = &[100, 200, 150, 255, 0];

let intvec = LEIntVec::builder(data)
    .codec(CodecSpec::FixedLength { num_bits: Some(8) })
    .build()
    .unwrap();

// For FixedLength, sampling rate is not applicable.
assert_eq!(intvec.get_sampling_rate(), None);
assert_eq!(intvec.get(1), Some(200));

// Building fails if a value does not fit.
let data_too_large: &[u64] = &[100, 200, 300]; // 300 does not fit in 8 bits
let result = LEIntVec::builder(data_too_large)
    .codec(CodecSpec::FixedLength { num_bits: Some(8) })
    .build();
assert!(matches!(result, Err(IntVecError::InvalidParameters(_))));

Implementation Notes

After writing the compressed bitstream, this method calls shrink_to_fit on the underlying Vec<u64> used for storage. While this may incur a one-time cost of reallocation and copying, it ensures that the final IntVec occupies the minimum necessary memory, which is critical for a data structure focused on compression.

Trait Implementations

impl<'a, E: Debug + Endianness> Debug for IntVecBuilder<'a, E>

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

Formats the value using the given formatter.