Struct SeqVecSlice 

pub struct SeqVecSlice<'a, T: Storable, E: Endianness, B: AsRef<[u64]>> { /* private fields */ }

An immutable, zero-copy slice of a SeqVec.

This struct provides a view into a contiguous portion of a SeqVec without copying the underlying compressed data. It is created by the slice or split_at methods on a SeqVec.

All operations on a SeqVecSlice are relative to the start of the slice, not the parent vector. The slice contains a contiguous range of sequences.

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};

let sequences: &[&[u32]] = &[&[1, 2], &[3, 4, 5], &[6], &[7, 8, 9, 10]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

// Create a slice of sequences 1 through 2 (indices 1 and 2)
let slice = vec.slice(1, 2).unwrap();

assert_eq!(slice.len(), 2);

// Accessing a sequence within the slice
// Index 0 of the slice corresponds to sequence 1 of the original vector
let seq0: Vec<u32> = slice.get(0).unwrap().collect();
assert_eq!(seq0, vec![3, 4, 5]);

// Iterating over the slice
let all_values: Vec<Vec<u32>> = slice.iter()
    .map(|seq| seq.collect())
    .collect();
assert_eq!(all_values, vec![vec![3, 4, 5], vec![6]]);

Implementations

impl<'a, T: Storable, E: Endianness, B: AsRef<[u64]>> SeqVecSlice<'a, T, E, B>

pub fn len(&self) -> usize

Returns the number of sequences in the slice.

pub fn is_empty(&self) -> bool

Returns true if the slice contains no sequences.

pub fn get(&self, index: usize) -> Option<SeqIter<'_, T, E>>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Returns an iterator over the elements of the sequence at index within the slice, or None if the index is out of bounds.

The index is relative to the start of the slice.

pub unsafe fn get_unchecked(&self, index: usize) -> SeqIter<'_, T, E>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Returns an iterator over the elements of the sequence at index within the slice without bounds checking.

The index is relative to the start of the slice.

Safety

Calling this method with an out-of-bounds index is undefined behavior. The caller must ensure that index < self.len().

pub fn decode_vec(&self, index: usize) -> Option<Vec<T>>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Returns the sequence at index as a materialized Vec<T>, or None if the index is out of bounds.

This method fully decodes the sequence and allocates a new vector.

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};

let sequences: &[&[u32]] = &[&[1, 2], &[3, 4, 5], &[6]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

let slice = vec.slice(1, 2).unwrap();
assert_eq!(slice.decode_vec(0), Some(vec![3, 4, 5]));
assert_eq!(slice.decode_vec(1), Some(vec![6]));
assert_eq!(slice.decode_vec(2), None); // Out of bounds

pub unsafe fn decode_vec_unchecked(&self, index: usize) -> Vec<T>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Returns the sequence at index as a materialized Vec<T> without bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior.

pub fn decode_into(&self, index: usize, buf: &mut Vec<T>) -> Option<usize>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Decodes the sequence at index into a reusable buffer.

The buffer is cleared and then filled with the decoded sequence elements. Returns the number of elements decoded, or None if the index is out of bounds.

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};

let sequences: &[&[u32]] = &[&[1, 2], &[3, 4, 5], &[6]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

let slice = vec.slice(1, 2).unwrap();

let mut buf = Vec::new();
assert_eq!(slice.decode_into(0, &mut buf), Some(3));
assert_eq!(buf, vec![3, 4, 5]);

// Buffer is reused (cleared internally).
assert_eq!(slice.decode_into(1, &mut buf), Some(1));
assert_eq!(buf, vec![6]);

pub unsafe fn decode_into_unchecked( &self, index: usize, buf: &mut Vec<T>, ) -> usize

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Decodes sequence index into the provided buffer without bounds checking.

Safety

Calling this method with an out-of-bounds index is undefined behavior.

pub fn iter(&self) -> SeqVecSliceIter<'_, T, E, B>

where for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

Returns an iterator over the sequences in the slice.

impl<T, E, B> SeqVecSlice<'_, T, E, B>

where T: Storable + PartialEq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

pub fn binary_search(&self, sequence: &[T]) -> Result<usize, usize>

where T: Ord,

Binary searches this slice for a sequence matching the given elements.

If the sequence is found, returns Ok(usize) with the index of the matching sequence within the slice. If not found, returns Err(usize) with the insertion point to maintain order.

The comparison is performed element-by-element with early termination: sequences with different lengths or any differing element are ordered according to the first difference encountered.

Performance Note

Each binary search probe fully decodes a compressed sequence until a difference is found or the sequence ends. For log(n) probes, each decoding is O(m) where m is the sequence length. This is O(m * log n) overall.

• If sequences are short or differ early, early termination makes this very efficient.
• If sequences are very long and similar, decoding cost dominates.
• To extract a key from each sequence efficiently, use binary_search_by_key to extract a sortable key from the compressed data (e.g., first element) rather than the full sequence.

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};

let sequences: &[&[u32]] = &[&[1, 2], &[3, 4, 5], &[6, 7], &[8]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

let slice = vec.slice(0, 4).unwrap();

assert_eq!(slice.binary_search(&[3, 4, 5]), Ok(1));
assert_eq!(slice.binary_search(&[6, 7]), Ok(2));
assert_eq!(slice.binary_search(&[5]), Err(2)); // Would be inserted at index 2

pub fn binary_search_by<F>(&self, f: F) -> Result<usize, usize>

where F: FnMut(SeqIter<'_, T, E>) -> Ordering,

Binary searches this slice with a custom comparison function.

The comparison function receives a SeqIter for the probe sequence and should return the ordering relative to the target.

Performance Note

The closure receives a SeqIter for the probe sequence, which may require decoding the compressed data. Each probe can involve up to O(m) decoding operations where m is the sequence length.

• For fast key extraction (first element, hash, etc.), decode only what is needed within the closure and return early.
• To search by a pre-computed key, use binary_search_by_key instead, which is optimized for key-based comparisons.
• For comparisons requiring the full sequence, full decoding is unavoidable: O(m * log n).

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};
use std::cmp::Ordering;

let sequences: &[&[u32]] = &[&[1], &[1, 2], &[1, 2, 3], &[1, 2, 3, 4]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

let slice = vec.slice(0, 4).unwrap();

// Search by sequence length (decodes all elements)
let result = slice.binary_search_by(|probe| {
    let probe_len = probe.count();
    probe_len.cmp(&3)
});

assert_eq!(result, Ok(2));

// Search by first element only (early termination)
let result = slice.binary_search_by(|mut probe| {
    match probe.next() {
        Some(first) => first.cmp(&1),
        None => Ordering::Less,
    }
});

pub fn binary_search_by_key<K, F>(&self, b: &K, f: F) -> Result<usize, usize>

where F: FnMut(SeqIter<'_, T, E>) -> K, K: Ord,

Binary searches this slice with a key extraction function.

Examples

use compressed_intvec::seq::{SeqVec, LESeqVec};

let sequences: &[&[u32]] = &[&[10], &[20], &[30, 40], &[50]];
let vec: LESeqVec<u32> = SeqVec::from_slices(sequences)?;

let slice = vec.slice(0, 4).unwrap();

// Search by first element
let result = slice.binary_search_by_key(&30, |mut probe| probe.next().unwrap());
assert_eq!(result, Ok(2)); // Found sequence [30, 40]

Trait Implementations

impl<'a, T: Clone + Storable, E: Clone + Endianness, B: Clone + AsRef<[u64]>> Clone for SeqVecSlice<'a, T, E, B>

fn clone(&self) -> SeqVecSlice<'a, T, E, B>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a, T: Debug + Storable, E: Debug + Endianness, B: Debug + AsRef<[u64]>> Debug for SeqVecSlice<'a, T, E, B>

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

Formats the value using the given formatter.

impl<'a, T, E, B> IntoIterator for &'a SeqVecSlice<'a, T, E, B>

where T: Storable, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

fn into_iter(self) -> Self::IntoIter

Returns an iterator over the sequences in the slice.

This implementation allows slices to be used in for loops:

for seq in &slice {
    // Process each sequence
}

type Item = SeqIter<'a, T, E>

The type of the elements being iterated over.

type IntoIter = SeqVecSliceIter<'a, T, E, B>

Which kind of iterator are we turning this into?

impl<'a, T, E, B> PartialEq<&SeqVec<T, E, B>> for SeqVecSlice<'a, T, E, B>

where T: Storable + PartialEq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

fn eq(&self, other: &&SeqVec<T, E, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T, E, B> PartialEq<SeqVec<T, E, B>> for SeqVecSlice<'a, T, E, B>

where T: Storable + PartialEq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

fn eq(&self, other: &SeqVec<T, E, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T, E, B> PartialEq<SeqVecSlice<'a, T, E, B>> for SeqVec<T, E, B>

where T: Storable + PartialEq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

fn eq(&self, other: &SeqVecSlice<'a, T, E, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T, E, B> PartialEq for SeqVecSlice<'a, T, E, B>

where T: Storable + PartialEq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,

fn eq(&self, other: &SeqVecSlice<'a, T, E, B>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a, T, E, B> Eq for SeqVecSlice<'a, T, E, B>

where T: Storable + Eq, E: Endianness, B: AsRef<[u64]>, for<'b> BufBitReader<E, MemWordReader<u64, &'b [u64], true>, DefaultReadParams>: BitRead<E, Error = Infallible> + CodesRead<E> + BitSeek<Error = Infallible>,