Struct IntVecFromIterBuilder

pub struct IntVecFromIterBuilder<E: Endianness, I: IntoIterator<Item = u64>> { /* private fields */ }

A builder for creating an IntVec from an iterator.

This builder is obtained by calling IntVec::from_iter_builder. It is designed for scenarios where data is too large to fit in memory as a Vec<u64> or is generated on-the-fly.

Limitations

This builder does not support automatic parameter selection for codecs. Because the data is processed in a stream, the builder cannot analyze it beforehand to determine optimal parameters. You must provide a CodecSpec with fixed, pre-determined parameters.

Implementations

impl<E: Endianness, I: IntoIterator<Item = u64>> IntVecFromIterBuilder<E, I>

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

Sets the sampling rate k for DSI-based codecs.

Refer to IntVecBuilder::k for more details.

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

Sets the codec specification.

The provided CodecSpec must have all parameters explicitly defined, as automatic parameter selection is not supported for iterator-based building.

Arguments

• codec_spec: The desired codec specification with fixed parameters.

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

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

Builds the IntVec by consuming the iterator.

This method iterates through the provided data, encodes it according to the specified codec, and constructs the final IntVec.

Returns

A Result containing the constructed IntVec on success, or an IntVecError on failure. Errors can occur if:

• An automatic or parameter-less codec spec is provided (e.g., CodecSpec::Auto).
• k=0 is used with a DSI-based codec.
• A value from the iterator does not fit within the specified number of bits for FixedLength encoding.

Example

use compressed_intvec::prelude::*;

// Create an IntVec from a range iterator.
let intvec = LEIntVec::from_iter_builder(0..1000u64)
    .codec(CodecSpec::FixedLength{ num_bits: Some(10) }) // 1000 fits in 10 bits
    .build()
    .unwrap();

assert_eq!(intvec.len(), 1000);
assert_eq!(intvec.get(999), Some(999));

// Building fails if automatic parameter selection is attempted.
let result = LEIntVec::from_iter_builder(0..100u64)
    .codec(CodecSpec::Auto)
    .build();
assert!(matches!(result, Err(IntVecError::InvalidParameters(_))));

Implementation Notes

Similar to the slice-based builder, this method calls shrink_to_fit on the underlying storage vector to ensure minimal memory usage. This brings an additional cost of reallocation and copying, but is necessary for a compressed data structure. However, this is a one-time cost and does not affect the overall performance of the IntVec in typical use cases.

Trait Implementations

impl<E: Debug + Endianness, I: Debug + IntoIterator<Item = u64>> Debug for IntVecFromIterBuilder<E, I>

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

Formats the value using the given formatter.