Struct sprs::CsVecBase

pub struct CsVecBase<IStorage, DStorage> { /* fields omitted */ }

A sparse vector, storing the indices of its non-zero data.

A CsVec represents a sparse vector by storing a sorted indices() array containing the locations of the non-zero values and a data() array containing the corresponding values. The format is compatible with CsMat, ie a CsVec can represent the row of a CSR matrix without any copying.

Similar to CsMat and TriMat, the CsVecBase type is parameterized over the indexing storage backend IStorage and the data storage backend DStorage. Type aliases are provided for common cases: CsVec represents a sparse vector owning its data, with Vecs as storage backends; CsVecView represents a sparse vector borrowing its data, using slices as storage backends; and CsVecViewMut represents a sparse vector that mutably borrows its data (but immutably borrows its indices).

Additionaly, the type aliases CsVecI, CsVecViewI, and CsVecViewMutI can be used to choose an index type different from the default usize.

Methods

impl<N, I: SpIndex> CsVecBase<Vec<I>, Vec<N>>

Methods operating on owning sparse vectors

pub fn new(n: usize, indices: Vec<I>, data: Vec<N>) -> CsVecI<N, I> where
    N: Copy, 

Create an owning CsVec from vector data.

Panics

• if indices and data lengths differ
• if the vector contains out of bounds indices

pub fn empty(dim: usize) -> CsVecI<N, I>

Create an empty CsVec, which can be used for incremental construction

pub fn append(&mut self, ind: usize, val: N)

Append an element to the sparse vector. Used for incremental building of the CsVec. The append should preserve the structure of the vector, ie the newly added index should be strictly greater than the last element of indices.

Panics

• Panics if ind is lower or equal to the last element of self.indices()
• Panics if ind is greater than self.dim()

pub fn reserve(&mut self, size: usize)

Reserve size additional non-zero values.

pub fn reserve_exact(&mut self, exact_size: usize)

Reserve exactly exact_size non-zero values.

pub fn clear(&mut self)

Clear the underlying storage

impl<N, I, IStorage, DStorage> CsVecBase<IStorage, DStorage> where
    I: SpIndex,
    IStorage: Deref<Target = [I]>,
    DStorage: Deref<Target = [N]>, 

Common methods of sparse vectors

pub fn view(&self) -> CsVecViewI<N, I>

Get a view of this vector.

Important traits for VectorIterator<'a, N, I>

impl<'a, N: 'a, I: 'a + SpIndex> Iterator for VectorIterator<'a, N, I> type Item = (usize, &'a N);

pub fn iter(&self) -> VectorIterator<N, I>

Iterate over the non zero values.

Example

use sprs::CsVec;
let v = CsVec::new(5, vec![0, 2, 4], vec![1., 2., 3.]);
let mut iter = v.iter();
assert_eq!(iter.next(), Some((0, &1.)));
assert_eq!(iter.next(), Some((2, &2.)));
assert_eq!(iter.next(), Some((4, &3.)));
assert_eq!(iter.next(), None);

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

The underlying indices.

pub fn data(&self) -> &[N]

The underlying non zero values.

pub fn into_raw_storage(self) -> (IStorage, DStorage)

Destruct the vector object and recycle its storage containers.

pub fn dim(&self) -> usize

The dimension of this vector.

pub fn nnz(&self) -> usize

The non zero count of this vector.

pub fn check_structure(&self) -> Result<(), SprsError>

Check the sparse structure, namely that:

• indices is sorted
• indices are lower than dims()

pub fn to_owned(&self) -> CsVecI<N, I> where
    N: Clone, 

Allocate a new vector equal to this one.

pub fn to_other_types<I2>(&self) -> CsVecI<N, I2> where
    N: Clone,
    I2: SpIndex, 

Clone the vector with another integer type for its indices

Panics

If the indices cannot be represented by the requested integer type.

pub fn row_view(&self) -> CsMatBase<N, I, Array2<I>, &'a [I], &'a [N]>

View this vector as a matrix with only one row.

pub fn col_view(&self) -> CsMatBase<N, I, Array2<I>, &'a [I], &'a [N]>

View this vector as a matrix with only one column.

pub fn get<'a>(&'a self, index: usize) -> Option<&'a N> where
    I: 'a, 

Access element at given index, with logarithmic complexity

pub fn nnz_index(&self, index: usize) -> Option<NnzIndex>

Find the non-zero index of the requested dimension index, returning None if no non-zero is present at the requested location.

Looking for the NnzIndex is done with logarithmic complexity, but once it is available, the NnzIndex enables retrieving the data with O(1) complexity.

pub fn dot<'b, T: IntoSparseVecIter<'b, N>>(&'b self, rhs: T) -> N where
    N: 'b + Num + Copy + Sum,
    I: 'b,
    <T as IntoSparseVecIter<'b, N>>::IterType: Iterator<Item = (usize, &'b N)>,
    T: Copy, 

Sparse vector dot product. The right-hand-side can be any type that can be interpreted as a sparse vector (hence sparse vectors, std vectors and slices, and ndarray's dense vectors work).

However, even if dense vectors work, it is more performant to use the dot_dense.

Panics

If the dimension of the vectors do not match.

Example

use sprs::CsVec;
let v1 = CsVec::new(8, vec![1, 2, 4, 6], vec![1.; 4]);
let v2 = CsVec::new(8, vec![1, 3, 5, 7], vec![2.; 4]);
assert_eq!(2., v1.dot(&v2));
assert_eq!(4., v1.dot(&v1));
assert_eq!(16., v2.dot(&v2));

pub fn dot_dense<T>(&self, rhs: T) -> N where
    T: DenseVector<N>,
    N: Num + Copy + Sum, 

Sparse-dense vector dot product. The right-hand-side can be any type that can be interpreted as a dense vector (hence std vectors and slices, and ndarray's dense vectors work).

Since the dot method can work with the same performance on dot vectors, the main interest of this method is to enforce at compile time that the rhs is dense.

Panics

If the dimension of the vectors do not match.

pub fn scatter(&self, out: &mut [N]) where
    N: Clone, 

Fill a dense vector with our values

pub fn to_set(&self) -> HashSet<(usize, N)> where
    N: Hash + Eq + Clone, 

Transform this vector into a set of (index, value) tuples

pub fn map<F>(&self, f: F) -> CsVecI<N, I> where
    F: FnMut(&N) -> N,
    N: Clone, 

Apply a function to each non-zero element, yielding a new matrix with the same sparsity structure.

impl<'a, N, I, IStorage, DStorage> CsVecBase<IStorage, DStorage> where
    N: 'a,
    I: 'a + SpIndex,
    IStorage: 'a + Deref<Target = [I]>,
    DStorage: DerefMut<Target = [N]>, 

Methods on sparse vectors with mutable access to their data

pub fn view_mut(&mut self) -> CsVecViewMutI<N, I>

pub fn get_mut(&mut self, index: usize) -> Option<&mut N>

Access element at given index, with logarithmic complexity

pub fn map_inplace<F>(&mut self, f: F) where
    F: FnMut(&N) -> N, 

Apply a function to each non-zero element, mutating it

Important traits for VectorIteratorMut<'a, N, I>

impl<'a, N: 'a, I: 'a + SpIndex> Iterator for VectorIteratorMut<'a, N, I> type Item = (usize, &'a mut N);

pub fn iter_mut(&mut self) -> VectorIteratorMut<N, I>

Mutable iteration over the non-zero values of a sparse vector

Only the values can be changed, the sparse structure is kept.

impl<'a, N: 'a, I: 'a + SpIndex> CsVecBase<&'a [I], &'a [N]>

Methods propagating the lifetime of a CsVecViewI.

pub fn new_view(
    n: usize,
    indices: &'a [I],
    data: &'a [N]
) -> Result<CsVecViewI<'a, N, I>, SprsError>

Create a borrowed CsVec over slice data.

pub fn get_rbr(&self, index: usize) -> Option<&'a N>

Access element at given index, with logarithmic complexity

Re-borrowing version of at().

pub unsafe fn new_view_raw(
    n: usize,
    nnz: usize,
    indices: *const I,
    data: *const N
) -> CsVecViewI<'a, N, I>

Create a borrowed CsVec over slice data without checking the structure This is unsafe because algorithms are free to assume that properties guaranteed by check_structure are enforced. For instance, non out-of-bounds indices can be relied upon to perform unchecked slice access.

impl<'a, N, I> CsVecBase<&'a [I], &'a mut [N]> where
    N: 'a,
    I: 'a + SpIndex, 

Methods propagating the lifetome of a CsVecViewMutI.

pub unsafe fn new_view_mut_raw(
    n: usize,
    nnz: usize,
    indices: *const I,
    data: *mut N
) -> CsVecViewMutI<'a, N, I>

Create a borrowed CsVec over slice data without checking the structure This is unsafe because algorithms are free to assume that properties guaranteed by check_structure are enforced, and because the lifetime of the pointers is unconstrained. For instance, non out-of-bounds indices can be relied upon to perform unchecked slice access. For safety, lifetime of the resulting vector should match the lifetime of the input pointers.

Trait Implementations

impl<N, IS, DS: Deref<Target = [N]>> VecDim<N> for CsVecBase<IS, DS>

fn dim(&self) -> usize

The dimension of the vector

impl<'a, N: 'a, I: 'a, IS, DS> IntoSparseVecIter<'a, N> for &'a CsVecBase<IS, DS> where
    I: SpIndex,
    IS: Deref<Target = [I]>,
    DS: Deref<Target = [N]>, 

type IterType = VectorIterator<'a, N, I>

fn dim(&self) -> usize

The dimension of the vector

Important traits for VectorIterator<'a, N, I>

impl<'a, N: 'a, I: 'a + SpIndex> Iterator for VectorIterator<'a, N, I> type Item = (usize, &'a N);

fn into_sparse_vec_iter(self) -> VectorIterator<'a, N, I>

Transform self into an iterator that yields (usize, &N) tuples where the usize is the index of the value in the sparse vector. The indices should be sorted.

fn is_dense(&self) -> bool

Indicator to check whether the vector is actually dense

fn index(self, idx: usize) -> &'a N where
    Self: Sized, 

Random access to an element in the vector.

impl<IStorage: PartialEq, DStorage: PartialEq> PartialEq<CsVecBase<IStorage, DStorage>> for CsVecBase<IStorage, DStorage>

fn eq(&self, other: &CsVecBase<IStorage, DStorage>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &CsVecBase<IStorage, DStorage>) -> bool

This method tests for !=.

impl<IStorage: Clone, DStorage: Clone> Clone for CsVecBase<IStorage, DStorage>

fn clone(&self) -> CsVecBase<IStorage, DStorage>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<IStorage: Debug, DStorage: Debug> Debug for CsVecBase<IStorage, DStorage>

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

Formats the value using the given formatter.

impl<N, I, IS1, DS1, IS2, DS2> Add<CsVecBase<IS2, DS2>> for CsVecBase<IS1, DS1> where
    N: Copy + Num,
    I: SpIndex,
    IS1: Deref<Target = [I]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [I]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the + operator.

fn add(self, rhs: CsVecBase<IS2, DS2>) -> CsVecI<N, I>

Performs the + operation.

impl<'a, N, I, IS1, DS1, IS2, DS2> Add<&'a CsVecBase<IS2, DS2>> for CsVecBase<IS1, DS1> where
    N: Copy + Num,
    I: SpIndex,
    IS1: Deref<Target = [I]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [I]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the + operator.

fn add(self, rhs: &CsVecBase<IS2, DS2>) -> CsVecI<N, I>

Performs the + operation.

impl<'a, N, I, IS1, DS1, IS2, DS2> Add<CsVecBase<IS2, DS2>> for &'a CsVecBase<IS1, DS1> where
    N: Copy + Num,
    I: SpIndex,
    IS1: Deref<Target = [I]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [I]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the + operator.

fn add(self, rhs: CsVecBase<IS2, DS2>) -> CsVecI<N, I>

Performs the + operation.

impl<'a, 'b, N, I, IS1, DS1, IS2, DS2> Add<&'b CsVecBase<IS2, DS2>> for &'a CsVecBase<IS1, DS1> where
    N: Copy + Num,
    I: SpIndex,
    IS1: Deref<Target = [I]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [I]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the + operator.

fn add(self, rhs: &CsVecBase<IS2, DS2>) -> CsVecI<N, I>

Performs the + operation.

impl<'a, 'b, N, IS1, DS1, IS2, DS2> Sub<&'b CsVecBase<IS2, DS2>> for &'a CsVecBase<IS1, DS1> where
    N: Copy + Num,
    IS1: Deref<Target = [usize]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [usize]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVec<N>

The resulting type after applying the - operator.

fn sub(self, rhs: &CsVecBase<IS2, DS2>) -> CsVec<N>

Performs the - operation.

impl<'a, 'b, N, I, IS1, DS1, IpS2, IS2, DS2> Mul<&'b CsMatBase<N, I, IpS2, IS2, DS2>> for &'a CsVecBase<IS1, DS1> where
    N: 'a + Copy + Num + Default,
    I: 'a + SpIndex,
    IS1: 'a + Deref<Target = [I]>,
    DS1: 'a + Deref<Target = [N]>,
    IpS2: 'b + Deref<Target = [I]>,
    IS2: 'b + Deref<Target = [I]>,
    DS2: 'b + Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the * operator.

fn mul(self, rhs: &CsMatBase<N, I, IpS2, IS2, DS2>) -> CsVecI<N, I>

Performs the * operation.

impl<'a, 'b, N, I, IpS1, IS1, DS1, IS2, DS2> Mul<&'b CsVecBase<IS2, DS2>> for &'a CsMatBase<N, I, IpS1, IS1, DS1> where
    N: Copy + Num + Default + Sum,
    I: SpIndex,
    IpS1: Deref<Target = [I]>,
    IS1: Deref<Target = [I]>,
    DS1: Deref<Target = [N]>,
    IS2: Deref<Target = [I]>,
    DS2: Deref<Target = [N]>, 

type Output = CsVecI<N, I>

The resulting type after applying the * operator.

fn mul(self, rhs: &CsVecBase<IS2, DS2>) -> CsVecI<N, I>

Performs the * operation.

impl<N, IS, DS> Index<usize> for CsVecBase<IS, DS> where
    IS: Deref<Target = [usize]>,
    DS: Deref<Target = [N]>, 

type Output = N

The returned type after indexing.

fn index(&self, index: usize) -> &N

Performs the indexing (container[index]) operation.

impl<N, IS, DS> Index<NnzIndex> for CsVecBase<IS, DS> where
    IS: Deref<Target = [usize]>,
    DS: Deref<Target = [N]>, 

type Output = N

The returned type after indexing.

fn index(&self, index: NnzIndex) -> &N

Performs the indexing (container[index]) operation.

impl<N, IS, DS> IndexMut<usize> for CsVecBase<IS, DS> where
    IS: Deref<Target = [usize]>,
    DS: DerefMut<Target = [N]>, 

fn index_mut(&mut self, index: usize) -> &mut N

Performs the mutable indexing (container[index]) operation.

impl<N, IS, DS> IndexMut<NnzIndex> for CsVecBase<IS, DS> where
    IS: Deref<Target = [usize]>,
    DS: DerefMut<Target = [N]>, 

fn index_mut(&mut self, index: NnzIndex) -> &mut N

Performs the mutable indexing (container[index]) operation.

impl<IStorage, DStorage> Serialize for CsVecBase<IStorage, DStorage> where
    IStorage: Serialize,
    DStorage: Serialize, 

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

Serialize this value into the given Serde serializer.

impl<'de, IStorage, DStorage> Deserialize<'de> for CsVecBase<IStorage, DStorage> where
    IStorage: Deserialize<'de>,
    DStorage: Deserialize<'de>, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.