Struct SIntVecBuilder

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

A builder for creating an SIntVec from a slice of signed integers (&[i64]).

This builder handles the conversion from signed to unsigned integers by applying the ZigZag transformation to each element on the fly. The resulting stream of u64 values is then passed to the underlying IntVec iterator-based builder for compression.

Limitations

This builder does not support automatic parameter selection for codecs. Because the data is transformed and consumed as a stream, the builder cannot analyze the entire dataset beforehand to determine optimal parameters. You must provide a CodecSpec with fixed, pre-determined parameters.

Attempting to use CodecSpec::Auto or variants with None parameters (e.g., CodecSpec::FixedLength { num_bits: None }) will result in an IntVecError::InvalidParameters.

Example

use compressed_intvec::prelude::*;

let data: &[i64] = &[-10, 20, -30, -40, 50];

// We must specify a codec with fixed parameters.
let sintvec = LESIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .k(16)
    .build()
    .unwrap();

assert_eq!(sintvec.len(), 5);
assert_eq!(sintvec.get(2), Some(-30));

Implementations

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

pub fn new(input: &'a [i64]) -> Self

Creates a new builder from a slice of i64.

By default, it is configured with a sampling rate (k) of 32 and uses Gamma coding as a safe, parameter-free default.

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

Sets the sampling rate k for the underlying IntVec.

The sampling rate determines the trade-off between random access speed and memory overhead for variable-length codes. It must be greater than 0. This parameter is ignored when using FixedLength encoding.

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

Sets the codec specification for compression.

The provided CodecSpec must have fixed, user-specified parameters. Automatic parameter selection (e.g., CodecSpec::Auto) is not supported and will cause the build method to return an error.

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

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

Builds the SIntVec by transforming and compressing the input data.

This method consumes the builder and returns a Result. The underlying logic uses the iterator-based builder of IntVec to avoid materializing the intermediate ZigZag-encoded u64 vector in memory.

Errors

This method will return an IntVecError if:

• A CodecSpec requiring automatic parameter selection is used.
• A value in the input data (after ZigZag encoding) is too large to fit within the specified number of bits for FixedLength encoding.
• The sampling rate k is set to 0 for a variable-length code.