Struct SparseVector 

pub struct SparseVector { /* private fields */ }

A learned-sparse vector: {term_id -> weight} over a high-cardinality vocabulary (e.g. SPLADE-v3 / BGE-M3 sparse head over a ~30k-term BERT vocab).

Stored as two parallel arrays — indices (term ids) and values (weights) — with indices kept strictly ascending so that the canonical scoring kernel (crate::ops::sparse_dot) is a linear merge-join. The invariant is enforced at construction by SparseVector::new.

The in-memory and binary forms keep weights as lossless f32. Weight quantization (8-bit, etc.) is a storage-engine concern applied at the index postings boundary, never in this type, so a brute-force scorer over SparseVector is always an exact ground truth.

Implementations

impl SparseVector

pub fn new(indices: Vec<u32>, values: Vec<f32>) -> Result<Self, SparseError>

Construct a sparse vector, validating its invariants:

• indices.len() == values.len() (SV-1),
• indices strictly ascending — sorted and unique (SV-2),
• every weight finite — no NaN / ±inf (SV-3).

Use SparseVector::from_pairs for unsorted input with duplicate term ids (the typical embedding-producer shape).

pub fn from_pairs(pairs: Vec<(u32, f32)>) -> Result<Self, SparseError>

Build from arbitrary (term_id, weight) pairs: sorts by term id and sums the weights of duplicate term ids, then validates. This is the ingestion-friendly constructor for embedding-model output and for dict[int, float] from the Python surface.

Non-finite input weights are still rejected (after summation).

pub fn indices(&self) -> &[u32]

The (strictly ascending) term ids.

pub fn values(&self) -> &[f32]

The weights, parallel to SparseVector::indices.

pub fn len(&self) -> usize

Number of non-zero terms.

pub fn is_empty(&self) -> bool

Whether the vector has no non-zero terms.

pub fn iter(&self) -> impl Iterator<Item = (u32, f32)> + '_

Iterate over (term_id, weight) pairs in ascending term-id order.

pub fn into_parts(self) -> (Vec<u32>, Vec<f32>)

Consume the vector into its parallel arrays.

Trait Implementations

impl Clone for SparseVector

fn clone(&self) -> SparseVector

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SparseVector

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SparseVector

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for SparseVector

fn eq(&self, other: &SparseVector) -> 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 Serialize for SparseVector

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SparseVector