Struct CsVecBuilder 

pub struct CsVecBuilder<'a, T> { /* private fields */ }

A builder for constructing sparse vectors efficiently.

This builder allows efficient construction of sparse vectors by adding elements in order. When the builder is dropped, the vector is automatically finalized and added to the parent matrix.

Features

• Automatic filtering of values below zero threshold
• Validation of index ordering (must be in ascending order)
• Efficient batch operations
• Automatic finalization when dropped

Examples

use algebra_sparse::{CsMatrix, CsVecBuilder};
use nalgebra::DMatrix;

let mut matrix = CsMatrix::new(3);
{
    let mut builder = matrix.new_lane_builder(1e-10);
    builder.push(0, 1.0);
    builder.push(2, 2.0);
    // Vector is automatically added when builder goes out of scope
}

Implementations

impl<'a, T> CsVecBuilder<'a, T>

where T: Real,

pub fn new(m: &'a mut CsMatrix<T>, zero_threshold: T) -> Self

Creates a new sparse vector builder for the given matrix.

When the builder is dropped, a new lane will be added to the sparse matrix if the builder contains any non-zero elements.

Arguments

• m - A mutable reference to the sparse matrix
• zero_threshold - The threshold below which values are considered zero

pub fn from_parts_unchecked( secondary_indices: &'a mut Vec<usize>, primary_offsets: &'a mut Vec<usize>, values: &'a mut Vec<T>, mat_value_start: usize, zero_threshold: T, ) -> Self

Creates a builder from raw parts without checking validity.

Safety

This function does not validate the provided parts. Use with caution.

pub fn push_unchecked(&mut self, index: usize, value: T)

Pushes a value to the vector without checking if it is zero or if the index is in order.

Safety

This function bypasses validation checks. Ensure that:

• The value is not zero (above threshold)
• The index is in ascending order
• The index is within valid bounds

Arguments

• index - Index of the element
• value - Value to add

pub fn push(&mut self, col: usize, value: T)

Pushes a value to the vector with validation.

Arguments

• col - Column index of the element
• value - Value to add

Panics

Panics if:

• The value is zero (below threshold)
• The column index is not in ascending order

pub fn extend(&mut self, idx_values: impl IntoIterator<Item = (usize, T)>)

Pushes multiple values to the vector with validation.

Arguments

• idx_values - Iterator of (index, value) pairs

Panics

Panics if any of the values are zero or if the indices are not in ascending order.

pub fn extend_unchecked( &mut self, idx_values: impl IntoIterator<Item = (usize, T)>, )

Pushes multiple values to the vector without validation.

Safety

This function bypasses validation checks.

Arguments

• idx_values - Iterator of (index, value) pairs

pub fn extend_with_nonzeros( &mut self, idx_values: impl IntoIterator<Item = (usize, T)>, )

Pushes all non-zero values to the sparse vector.

This method automatically discards any values that are below the zero threshold. This is useful when converting from dense data where many values might be zero.

Arguments

• idx_values - Iterator of (index, value) pairs

pub fn finish(self) -> usize

Finishes the builder and returns the number of non-zero elements.

This method is called automatically when the builder is dropped, but can be called explicitly to get the count of non-zero elements.

Returns

The number of non-zero elements added

Note

If the number of non-zero elements is zero, the sparse vector will be discarded and not added to the matrix.

Trait Implementations

impl<T> Drop for CsVecBuilder<'_, T>

Automatically finalizes the sparse vector when the builder is dropped.

This implementation ensures that the sparse vector is properly added to the parent matrix when the builder goes out of scope. If no non-zero elements were added, the empty lane is discarded.

fn drop(&mut self)

Executes the destructor for this type.