Struct SIntVec

pub struct SIntVec<E: Endianness> { /* private fields */ }

A compressed, randomly accessible vector of signed i64 integers.

SIntVec acts as a wrapper around IntVec that transparently handles the encoding of signed integers (i64) into unsigned integers (u64) using the ZigZag transformation. This allows for efficient compression of typical signed integer distributions, where values are often clustered around zero.

All compression logic and storage are delegated to the inner IntVec. SIntVec simply provides a convenient API that accepts and returns i64 values.

Limitations

Unlike IntVec, the SIntVecBuilder requires that codec parameters be specified manually. Automatic parameter selection is not supported because the on-the-fly ZigZag transformation of the data prevents the builder from performing a pre-analysis pass to determine optimal codec parameters.

Example

use compressed_intvec::prelude::*;

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

// SIntVec requires manual codec selection. Let's use Gamma.
let sintvec = LESIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .k(4)
    .build()
    .unwrap();

assert_eq!(sintvec.len(), data.len());
assert_eq!(sintvec.get(0), Some(-10));
assert_eq!(sintvec.get(2), Some(30));

Implementations

impl<E> SIntVec<E>

where E: Endianness + Send + Sync, for<'a> BufBitReader<E, MemWordReader<u64, &'a Vec<u64>>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible> + Send,

pub fn par_iter(&self) -> impl ParallelIterator<Item = i64> + '_

Returns a parallel iterator over the decompressed i64 values.

This method wraps the parallel iterator of the inner IntVec and applies the inverse ZigZag transformation to each element on the fly.

Performance

The performance characteristics are largely inherited from the underlying IntVec::par_iter. The additional to_int mapping is a trivial bitwise operation with negligible overhead. Therefore, the same trade-offs apply: this parallel iterator is most beneficial for computationally expensive codecs, while the sequential version may be faster for simple codecs where memory bandwidth is the bottleneck.

Example

use compressed_intvec::prelude::*;
use rayon::prelude::ParallelIterator;

let data: &[i64] = &[-10, 20, -30, -40, 50];
let sintvec = LESIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .build()
    .unwrap();

// Decompress the entire vector in parallel.
let collected: Vec<i64> = sintvec.par_iter().collect();
assert_eq!(collected, data);

pub fn par_get_many(&self, indices: &[usize]) -> Result<Vec<i64>, IntVecError>

Retrieves multiple signed integers in parallel.

This method leverages the parallel IntVec::par_get_many of the inner IntVec to fetch the compressed data and then transforms the results back to signed integers.

Implementation Notes

The decompression and random access work is performed in parallel by the inner IntVec. Once the u64 (ZigZag-encoded) values are retrieved, this method performs a fast, sequential pass to apply the inverse ZigZag transformation. This final conversion step is extremely lightweight and does not typically impact overall performance.

The performance trade-offs of this method are therefore identical to those of the underlying IntVec::par_get_many. It is most beneficial for

Example

use compressed_intvec::prelude::*;

let data: &[i64] = &[-10, 20, -30, -40, 50, 60];
let sintvec = LESIntVec::builder(data)
    .codec(CodecSpec::Gamma)
    .build()
    .unwrap();

let indices_to_get = vec![0, 2, 4];
let values = sintvec.par_get_many(&indices_to_get).unwrap();

// The results are returned in the same order as the requested indices.
assert_eq!(values, vec![-10, -30, 50]);

impl<E: Endianness> SIntVec<E>

where for<'a> BufBitReader<E, MemWordReader<u64, &'a Vec<u64>>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

pub fn builder(input: &[i64]) -> SIntVecBuilder<'_, E>

Returns a builder for creating an SIntVec from a slice (&[i64]).

This builder requires that codec parameters be specified manually because it transforms the data on-the-fly and cannot perform a pre-analysis pass.

Example

use compressed_intvec::prelude::*;

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

// Codec parameters must be fixed.
let sintvec = LESIntVec::builder(data)
    .codec(CodecSpec::Delta)
    .build()
    .unwrap();

assert_eq!(sintvec.get(1), Some(20));

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

Retrieves the signed integer at the specified index.

This method retrieves the underlying compressed u64 value from the inner IntVec and then applies the inverse ZigZag transformation to restore the original i64 value.

Example

use compressed_intvec::prelude::*;

let data: &[i64] = &[-10, 20, 30, -40, 50];
let sintvec = LESIntVec::builder(data).codec(CodecSpec::Gamma).build().unwrap();

assert_eq!(sintvec.get(0), Some(-10));
assert_eq!(sintvec.get(4), Some(50));
assert_eq!(sintvec.get(99), None); // Out of bounds

pub fn iter(&self) -> SIntVecIter<'_, E>

Returns an iterator over the decompressed i64 values.

The iterator wraps the inner IntVec’s iterator and applies the inverse ZigZag transformation to each value on the fly.

Example

use compressed_intvec::prelude::*;

let data: &[i64] = &[10, -20, 30, -40, 50];
let sintvec = LESIntVec::builder(data).codec(CodecSpec::Gamma).build().unwrap();

let collected: Vec<i64> = sintvec.iter().collect();
assert_eq!(collected, data);

pub fn len(&self) -> usize

Returns the number of elements in the vector. This is delegated to the inner IntVec.

pub fn is_empty(&self) -> bool

Returns true if the vector contains no elements. This is delegated to the inner IntVec.

Example

use compressed_intvec::prelude::*;

let empty_sintvec = LESIntVec::builder(&[]).codec(CodecSpec::Gamma).build().unwrap();
assert!(empty_sintvec.is_empty());
assert_eq!(empty_sintvec.len(), 0);

pub fn encoding(&self) -> Encoding

Returns the underlying Encoding used for compression. This is delegated to the inner IntVec.

pub fn get_sampling_rate(&self) -> Option<usize>

Returns the sampling rate k used during encoding, if applicable. This is delegated to the inner IntVec.

Trait Implementations

impl<E: Clone + Endianness> Clone for SIntVec<E>

fn clone(&self) -> SIntVec<E>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<E: Endianness> CopyType for SIntVec<E>

where IntVec<E>: MemSize,

type Copy = False

impl<E: Debug + Endianness> Debug for SIntVec<E>

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

Formats the value using the given formatter.

impl<E: Endianness> MemDbgImpl for SIntVec<E>

where IntVec<E>: MemDbgImpl,

fn _mem_dbg_rec_on( &self, _memdbg_writer: &mut impl Write, _memdbg_total_size: usize, _memdbg_max_depth: usize, _memdbg_prefix: &mut String, _memdbg_is_last: bool, _memdbg_flags: DbgFlags, ) -> Result

fn _mem_dbg_depth_on( &self, writer: &mut impl Write, total_size: usize, max_depth: usize, prefix: &mut String, field_name: Option<&str>, is_last: bool, padded_size: usize, flags: DbgFlags, ) -> Result<(), Error>

impl<E: Endianness> MemSize for SIntVec<E>

where IntVec<E>: MemSize,

fn mem_size(&self, _memsize_flags: SizeFlags) -> usize

Returns the (recursively computed) overall memory size of the structure in bytes.