Struct sparse::coo::CooMat

pub struct CooMat<T> { /* fields omitted */ }

Coordinate (COO) format sparse matrix.

Format

The coordinate storage format stores tuples (row, col, value) for each non-zero element of the matrix.

Properties

• The coordinate format is intented for incremental matrix constructions.
• The coordinate format allows duplicates.
• When a COO matrix is converted to a compressed format (CSC or CSR), duplicate entries are summed up.

Storage

Let A a 3-by-4 (real) matrix with 6 non-zero entries:

    | 0 1 0 2 |
A = | 0 0 3 0 |
    | 4 5 6 0 |

In arbitrary order, ‘A’ may be stored as follows:

(row, col, val) idx
(0, 1, 1.0)     [0]
(1, 2, 3.0)     [1]
(2, 1, 5.0)     [2]
(0, 3, 2.0)     [3]
(2, 0, 4.0)     [4]
(2, 2, 6.0)     [5]

In row major order, A is stored as follows:

(row, col, val) idx
(0, 1, 1.0)     [0]
(0, 3, 2.0)     [1]
(1, 2, 3.0)     [2]
(2, 0, 4.0)     [3]
(2, 1, 5.0)     [4]
(2, 2, 6.0)     [5]
 ^
 | major

In column major order, A is stored as follows:

(row, col, val) idx
(2, 0, 4.0)     [0]
(0, 1, 1.0)     [1]
(2, 1, 5.0)     [2]
(1, 2, 3.0)     [3]
(2, 2, 6.0)     [4]
(0, 3, 2.0)     [5]
    ^
    | major

Constructors

CooMat provides multiple constructors:

use sparse::CooMat;

// Create an empty COO matrix
let rows = 2;
let cols = 3;
let a = CooMat::<f64>::new(rows, cols);

// Create an empty COO matrix with initial capacity
let rows = 2;
let cols = 3;
let capacity = 6;
let b = CooMat::<f64>::with_capacity(rows, cols, capacity);

// Create a COO matrix with initial entries from entry vector
// Providing shape ...
let rows = 2;
let cols = 2;
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let c = CooMat::with_entries(rows, cols, entries);
// ... or not (rows = max(row), cols = max(col))
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let c: CooMat<f64> = entries.into_iter().collect();

// Create a COO matrix with initial entries from triplet vectors
let rows = 2;
let cols = 2;
let rowind = vec![0, 1];
let colind = vec![0, 1];
let values = vec![1.0, 2.0];
let e = CooMat::with_triplets(rows, cols, rowind, colind, values);

Entry get/insertion/removal/clear

CooMat is intented for incremental matrix constructions and provides corresponding methods:

use sparse::CooMat;

let mut matrix = CooMat::with_capacity(3, 3, 9);
// matrix:
// | 0 0 0 |
// | 0 0 0 |
// | 0 0 0 |

// Insert new entries one by one
matrix.push(0, 0, 1.0);
matrix.push(0, 1, 2.0);
matrix.push(1, 0, 3.0);
matrix.push(1, 1, 4.0);
// matrix:
// | 1 2 0 |
// | 3 4 0 |
// | 0 0 0 |
// entries:
// (0, 0, 1.0) [0]
// (0, 1, 2.0) [1]
// (1, 0, 3.0) [2]
// (1, 1, 4.0) [3]
assert_eq!(matrix.len(), 4);

// Get an immutable reference to an entry
let entry = matrix.get(0);
assert_eq!(entry, Some((&0, &0, &1.0)));

// Get a mutable reference to an entry and modify it
// (only the value is mutable)
if let Some((r, c, v)) = matrix.get_mut(0) {
    *v *= -1.0;
}
// matrix:
// |-1 2 0 |
// | 3 4 0 |
// | 0 0 0 |
// entries:
// (0, 0,-1.0) [0]
// (0, 1, 2.0) [1]
// (1, 0, 3.0) [2]
// (1, 1, 4.0) [3]
let entry = matrix.get(0);
assert_eq!(entry, Some((&0, &0, &-1.0)));

// Extend the matrix with new entries
let entries = vec![
    (0, 2, 5.0),
    (1, 2, 6.0),
    (2, 1, 8.0),
    (2, 2, 9.0),
];
matrix.extend(entries);
// matrix:
// |-1 2 5 |
// | 3 4 6 |
// | 0 8 9 |
// entries:
// (0, 0,-1.0) [0]
// (0, 1, 2.0) [1]
// (1, 0, 3.0) [2]
// (1, 1, 4.0) [3]
// (0, 2, 5.0) [4] <|
// (1, 2, 6.0) [5] <|
// (2, 1, 8.0) [6] <|
// (2, 2, 9.0) [7] <|- entries added
assert_eq!(matrix.len(), 8);

// Insert new entry at specified index
matrix.insert(6, 2, 0, 7.0);
// matrix:
// |-1 2 5 |
// | 3 4 6 |
// | 7 8 9 |
// entries:
// (0, 0,-1.0) [0]
// (0, 1, 2.0) [1]
// (1, 0, 3.0) [2]
// (1, 1, 4.0) [3]
// (0, 2, 5.0) [4]
// (1, 2, 6.0) [5]
// (2, 0, 7.0) [6] <- entry inserted
// (2, 1, 8.0) [7] <|
// (2, 2, 9.0) [8] <|- indices shifted
assert_eq!(matrix.len(), 9);
assert_eq!(matrix.get(6), Some((&2, &0, &7.0)));

// Remove last entry
assert_eq!(matrix.pop(), Some((2, 2, 9.0)));
// matrix:
// |-1 2 5 |
// | 3 4 6 |
// | 7 8 0 |
// entries:
// (0, 0,-1.0) [0]
// (0, 1, 2.0) [1]
// (1, 0, 3.0) [2]
// (1, 1, 4.0) [3]
// (0, 2, 5.0) [4]
// (1, 2, 6.0) [5]
// (2, 0, 7.0) [6]
// (2, 1, 8.0) [7]
// (2, 2, 9.0) [x] <- entry removed
assert_eq!(matrix.len(), 8);

// Remove a specific entry
let entry = matrix.remove(1);
assert_eq!(entry, (0, 1, 2.0));
// matrix:
// |-1 0 5 |
// | 3 4 6 |
// | 7 8 0 |
// entries:
// (0, 0,-1.0) [0]
// (0, 1, 2.0) [x] <- entry removed
// (1, 0, 3.0) [1] <|
// (1, 1, 4.0) [2] <|
// (0, 2, 5.0) [3] <|
// (1, 2, 6.0) [4] <|
// (2, 0, 7.0) [5] <|
// (2, 1, 8.0) [6] <|- indices shifted
assert_eq!(matrix.len(), 7);

// Swap entries
matrix.swap(3, 5);
// matrix:
// |-1 0 7 |
// | 3 4 6 |
// | 5 8 0 |
// entries:
// (0, 0,-1.0) [0]
// (1, 0, 3.0) [1]
// (1, 1, 4.0) [2]
// (2, 0, 7.0) [3] <- entry swapped [5] -> [3]
// (1, 2, 6.0) [4]
// (0, 2, 5.0) [5] <- entry swapped [3] -> [5]
// (2, 1, 8.0) [6]
assert_eq!(matrix.get(3), Some((&2, &0, &7.0)));
assert_eq!(matrix.get(5), Some((&0, &2, &5.0)));

// Swap remove a specific entry
let entry = matrix.swap_remove(1);
assert_eq!(entry, (1, 0, 3.0));
// matrix:
// |-1 0 5 |
// | 0 4 6 |
// | 7 8 0 |
// entries:
// (0, 0,-1.0) [0]
// (1, 0, 3.0) [x] <- entry removed
// (2, 1, 8.0) [1] <- entry swapped [6] -> [1]
// (1, 1, 4.0) [2]
// (2, 0, 7.0) [3]
// (1, 2, 6.0) [4]
// (0, 2, 5.0) [5]
assert_eq!(matrix.len(), 6);
assert_eq!(matrix.get(1), Some((&2, &1, &8.0)));

// Retain entries
matrix.retain(|(r, c, _)| *r > 0 && *c > 0);
// matrix:
// |-1 0 5 |
// | 0 4 6 |
// | 7 8 0 |
// entries:
// (0, 0,-1.0) [x] <- entry removed
// (2, 1, 8.0) [0]
// (1, 1, 4.0) [1]
// (2, 0, 7.0) [x] <- entry removed
// (1, 2, 6.0) [2]
// (0, 2, 5.0) [x] <- entry removed
assert_eq!(matrix.len(), 3);
assert_eq!(matrix.get(0), Some((&2, &1, &8.0)));
assert_eq!(matrix.get(1), Some((&1, &1, &4.0)));
assert_eq!(matrix.get(2), Some((&1, &2, &6.0)));

// Clear matrix
matrix.clear();
assert!(matrix.is_empty())

Capacity and Length

The matrix capacity corresponds to the amount of space allocated for the matrix entries unlike the matrix length which corresponds to the number of entries in the matrix. Initially for empty matrices, no memory is allocated. If entries are inserted, matrix capacity will grow accordingly. The growth strategy is unspecified behavior and no guarentees are made.

CooMat provides multiple methods to manage matrix capacity and length:

use sparse::CooMat;

let mut matrix: CooMat<f64> = CooMat::new(2, 2);
// Initially capacity and length are 0
assert_eq!(matrix.capacity(), 0);
assert_eq!(matrix.len(), 0);

// Inserting an entry allocate space for at least one entry
matrix.push(0, 0, 1.0);
assert!(matrix.capacity() >= 1);
assert_eq!(matrix.len(), 1);

// Inserting other entries may reallocate
matrix.push(1, 1, 2.0);
assert!(matrix.capacity() >= 2);
assert_eq!(matrix.len(), 2);

// To prevent reallocation, capacity can be adjusted at construction time
let mut matrix: CooMat<f64> = CooMat::with_capacity(2, 2, 4);
assert_eq!(matrix.capacity(), 4);
assert!(matrix.is_empty());

// Pushing values will not reallocate
matrix.push(0, 0, 1.0);
assert_eq!(matrix.capacity(), 4);
assert_eq!(matrix.len(), 1);

// Additional capacity can be requested after construction
let mut matrix: CooMat<f64> = CooMat::with_capacity(2, 2, 1);
assert_eq!(matrix.capacity(), 1);
matrix.reserve(4);
assert!(matrix.capacity() >= 4);

// Capacity can be shrunk to fit (best effort) actual number of entries
let mut matrix: CooMat<f64> = CooMat::with_capacity(3, 3, 9);
assert_eq!(matrix.capacity(), 9);
matrix.push(1, 1, 1.0);
matrix.shrink();
assert!(matrix.capacity() < 9);

Iterators

CooMat also provides convenient Iterators/IntoIterator:

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);

// Immutable iterator over entries
let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

// Mutable iterator over entries
let mut iter = matrix.iter_mut();
for (r, c, v) in iter {
    *v *= 2.0;
}
let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &2.0)));
assert_eq!(iter.next(), Some((&0, &1, &4.0)));
assert_eq!(iter.next(), Some((&1, &0, &6.0)));
assert_eq!(iter.next(), Some((&1, &1, &8.0)));
assert_eq!(iter.next(), None);

// Turn matrix into iterator
for (r, c, v) in matrix {
    println!("row = {}, col = {}, value = {}", r, c, v);
}

Sorting

Sorting entries before iterating over matrix entries can be convenient. Coordinate matrix format can be sorted in row/column major order:

use sparse::CooMat;
let rows = 2;
let cols = 2;
let rowind = vec![0, 0, 1, 1];
let colind = vec![0, 1, 0, 1];
let values = vec![1.0, 2.0, 3.0, 4.0];
let mut matrix = CooMat::with_triplets(rows, cols, rowind, colind, values);
// matrix:
// | 1 2 |
// | 3 4 |

// Sort row major order
matrix.sort_unstable_row_major();
// Row major order: 1 -> 2 -> 3 -> 4
let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

// Sort column major order
matrix.sort_unstable_col_major();
// Col major order: 1 -> 3 -> 2 -> 4
let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

If sorting stability is not required, prefer sort_unstable_* variants for performance.

Implementations

impl<T> CooMat<T>

pub fn new(rows: usize, cols: usize) -> Self

Creates a coordinate format sparse matrix with specified shape (rows, cols).

The created matrix has following properties:

• the matrix is empty
• the matrix capacity is 0
• the matrix will not allocate memory before any insert/push operation

If rows or cols is 0 the corresponding dimension is set to 1.

Example

use sparse::CooMat;

// With type annotation ...
let matrix: CooMat<f64> = CooMat::new(2, 2);
assert_eq!(matrix.shape(), (2, 2));
assert!(matrix.is_empty());
assert_eq!(matrix.capacity(), 0);

// ... or with turbofish operator
let matrix = CooMat::<f64>::new(3, 4);
assert_eq!(matrix.shape(), (3, 4));
assert!(matrix.is_empty());
assert_eq!(matrix.capacity(), 0);

pub fn with_capacity(rows: usize, cols: usize, capacity: usize) -> Self

Creates a coordinate format sparse matrix with specified shape (rows, cols) and capacity.

The created matrix has following properties:

• the matrix is empty
• the matrix capacity is capacity
• the matrix will allocate memory for at least capacity entries

If rows or cols is 0 the corresponding dimension is set to 1.

Example

use sparse::CooMat;
let matrix = CooMat::<f64>::with_capacity(2, 2, 4);
assert_eq!(matrix.shape(), (2, 2));
assert!(matrix.is_empty());
assert_eq!(matrix.capacity(), 4);

pub fn with_entries<I>(rows: usize, cols: usize, entries: I) -> Self where
    I: IntoIterator<Item = (usize, usize, T)>, 

Creates a coordinate format sparse matrix with specified shape (rows, cols) and entries.

The created matrix has following properties:

• the matrix is filled with entries
• the matrix capacity is at least entries.len()

If rows or cols is 0 the corresponding dimension is set to 1.

Panics

Panics if any entry’s row or column index exceeds number of rows or columns respectively.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.shape(), (2, 2));
assert_eq!(matrix.len(), 4);
assert!(matrix.capacity() >= 4);

pub fn with_triplets<R, C, V>(
    rows: usize,
    cols: usize,
    rowind: R,
    colind: C,
    values: V
) -> Self where
    R: IntoIterator<Item = usize>,
    C: IntoIterator<Item = usize>,
    V: IntoIterator<Item = T>, 

Creates a coordinate format sparse matrix with specified shape (rows, cols) and triplets.

The created matrix has following properties:

• the matrix is filled with values.len() entries
• the matrix capacity is at least values.len()

Panics

Panics if

• any row or column index exceeds number of rows or columns respectively.
• rowind, colind and values length differ.

Example

use sparse::CooMat;
let rowind = vec![0, 0, 1, 1];
let colind = vec![0, 1, 0, 1];
let values = vec![1.0, 2.0, 3.0, 4.0];
let matrix = CooMat::with_triplets(2, 2, rowind, colind, values);
assert_eq!(matrix.shape(), (2, 2));
assert_eq!(matrix.len(), 4);
assert!(matrix.capacity() >= 4);

pub fn rows(&self) -> usize

Returns the number of rows of the matrix.

Example

use sparse::CooMat;
let matrix = CooMat::<f64>::new(1, 2);
assert_eq!(matrix.rows(), 1);

pub fn cols(&self) -> usize

Returns the number of cols of the matrix.

Example

use sparse::CooMat;
let matrix = CooMat::<f64>::new(1, 2);
assert_eq!(matrix.cols(), 2);

pub fn shape(&self) -> (usize, usize)

Returns the shape of the matrix.

Example

use sparse::CooMat;
let matrix = CooMat::<f64>::new(1, 2);
assert_eq!(matrix.shape(), (1, 2));

pub fn capacity(&self) -> usize

Returns the capacity of the matrix.

Example

use sparse::CooMat;
let matrix = CooMat::<f64>::with_capacity(1, 1, 42);
assert_eq!(matrix.capacity(), 42);

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

Reserve additional capacity for the matrix.

Example

use sparse::CooMat;
let mut matrix = CooMat::<f64>::new(1, 1);
assert_eq!(matrix.capacity(), 0);
matrix.reserve(10);
assert!(matrix.capacity() >= 10);

pub fn shrink(&mut self)

Shrink the capacity of the matrix.

Example

use sparse::CooMat;
let mut matrix = CooMat::<f64>::with_capacity(1, 1, 42);
assert_eq!(matrix.capacity(), 42);
matrix.shrink();
assert!(matrix.capacity() <= 42);

pub fn len(&self) -> usize

Returns the number of entries in the matrix.

This number is not the number of non zeros element in the matrix because duplicates are allowed.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.len(), 4);

pub fn is_empty(&self) -> bool

Returns true if the matrix contains no entry.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = CooMat::with_entries(2, 2, entries);
let empty = CooMat::<f64>::new(2, 2);
assert!(!matrix.is_empty());
assert!(empty.is_empty());

pub fn truncate(&mut self, len: usize)

Shortens the matrix to len.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.len(), 4);
matrix.truncate(4);
assert_eq!(matrix.len(), 4);
matrix.truncate(2);
assert_eq!(matrix.len(), 2);

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

Returns an immutable reference to the entry at specified index.

Example

use sparse::CooMat;
let entries = vec![(0, 0, 1.0)];
let matrix = CooMat::with_entries(1, 1, entries);
assert_eq!(matrix.get(0), Some((&0, &0, &1.0)));

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

Returns a mutable reference to the entry at specified index.

Example

use sparse::CooMat;
let entries = vec![(0, 0, 1.0)];
let mut matrix = CooMat::with_entries(1, 1, entries);
if let Some((_, _, v)) = matrix.get_mut(0) {
    *v *= 2.0;
}
assert_eq!(matrix.get(0), Some((&0, &0, &2.0)));

pub fn swap(&mut self, a: usize, b: usize)

Swaps two matrix entries.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(1, 2, entries);
assert_eq!(matrix.get(0), Some((&0, &0, &1.0)));
assert_eq!(matrix.get(1), Some((&0, &1, &2.0)));
matrix.swap(0, 1);
assert_eq!(matrix.get(0), Some((&0, &1, &2.0)));
assert_eq!(matrix.get(1), Some((&0, &0, &1.0)));

pub fn insert(&mut self, index: usize, row: usize, col: usize, val: T)

Inserts an entry to the matrix.

Panics

Panics if:

• row >= self.rows()
• col >= self.cols()
• index > self.len()

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.get(2), Some((&1, &1, &4.0)));
matrix.insert(2, 1, 0, 3.0);
assert_eq!(matrix.len(), 4);
assert_eq!(matrix.get(2), Some((&1, &0, &3.0)));
assert_eq!(matrix.get(3), Some((&1, &1, &4.0)));

pub fn remove(&mut self, index: usize) -> (usize, usize, T)

Remove an entry from the matrix.

Panics

Panics if index > self.len()

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.remove(2), (1, 0, 3.0));
assert_eq!(matrix.len(), 3);

pub fn swap_remove(&mut self, index: usize) -> (usize, usize, T)

Remove an entry from the matrix and swap with last entry.

Panics

Panics if index > self.len()

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.swap_remove(1), (0, 1, 2.0));
assert_eq!(matrix.len(), 3);
assert_eq!(matrix.get(1), Some((&1, &1, &4.0)));

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

Appends an entry to the matrix.

Panics

Panics if:

• row >= self.rows()
• col >= self.cols()

Example

use sparse::CooMat;
let mut matrix = CooMat::with_capacity(1, 1, 1);
matrix.push(0, 0, 1.0);
assert_eq!(matrix.len(), 1);
assert_eq!(matrix.get(0), Some((&0, &0, &1.0)));

pub fn pop(&mut self) -> Option<(usize, usize, T)>

Remove last entry from the matrix.

Example

use sparse::CooMat;
let entries = vec![(0, 0, 1.0), (1, 1, 2.0)];
let mut matrix = CooMat::with_entries(2, 2, entries);
assert_eq!(matrix.get(matrix.len() - 1), Some((&1, &1, &2.0)));
assert_eq!(matrix.pop(), Some((1, 1, 2.0)));
assert_eq!(matrix.get(matrix.len() - 1), Some((&0, &0, &1.0)));
assert_eq!(matrix.pop(), Some((0, 0, 1.0)));
assert!(matrix.is_empty());

pub fn retain<F>(&mut self, pred: F) where
    F: FnMut(&(usize, usize, T)) -> bool, 

Retains only the entries specified by the predicate.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.retain(|(r, c, _)| *r + *c != 1);
assert_eq!(matrix.len(), 2);
assert_eq!(matrix.get(0), Some((&0, &0, &1.0)));
assert_eq!(matrix.get(1), Some((&1, &1, &4.0)));

pub fn clear(&mut self)

Clears the matrix.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.clear();
assert!(matrix.is_empty());

pub fn sort_stable_row_major(&mut self)

Sort (stable) the matrix entries with row major order.

Example

use sparse::CooMat;
let entries = vec![
    (1, 1, 4.0),
    (0, 0, 1.0),
    (1, 0, 3.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.sort_stable_row_major();

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

pub fn sort_stable_col_major(&mut self)

Sort (stable) the matrix entries with column major order.

Example

use sparse::CooMat;
let entries = vec![
    (1, 1, 4.0),
    (0, 0, 1.0),
    (1, 0, 3.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.sort_stable_col_major();

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

pub fn sort_unstable_row_major(&mut self)

Sort (unstable) the matrix entries with row major order.

Example

use sparse::CooMat;
let entries = vec![
    (1, 1, 4.0),
    (0, 0, 1.0),
    (1, 0, 3.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.sort_unstable_row_major();

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

pub fn sort_unstable_col_major(&mut self)

Sort (unstable) the matrix entries with column major order.

Example

use sparse::CooMat;
let entries = vec![
    (1, 1, 4.0),
    (0, 0, 1.0),
    (1, 0, 3.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.sort_unstable_col_major();

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

pub fn reverse(&mut self)

Reverse matrix entries order.

Example

use sparse::CooMat;
let entries = vec![
    (1, 1, 4.0),
    (0, 0, 1.0),
    (1, 0, 3.0),
    (0, 1, 2.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);
matrix.sort_stable_row_major();

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

matrix.reverse();
let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), None);

pub fn iter(&self) -> Iter<'_, T>

An iterator visiting all entries of the matrix. The iterator element type is (&'a usize, &'a usize, &'a T).

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix = CooMat::with_entries(2, 2, entries);

let mut iter = matrix.iter();
assert_eq!(iter.next(), Some((&0, &0, &1.0)));
assert_eq!(iter.next(), Some((&0, &1, &2.0)));
assert_eq!(iter.next(), Some((&1, &0, &3.0)));
assert_eq!(iter.next(), Some((&1, &1, &4.0)));
assert_eq!(iter.next(), None);

pub fn iter_mut(&mut self) -> IterMut<'_, T>

An iterator visiting all mutable entries of the matrix. The iterator element type is (&'a usize, &'a usize, &'a mut T).

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix = CooMat::with_entries(2, 2, entries);

let mut iter = matrix.iter_mut();
for (_, _, v) in iter {
    *v *= 2.0;
}

let mut iter = matrix.iter_mut();
assert_eq!(iter.next(), Some((&0, &0, &mut 2.0)));
assert_eq!(iter.next(), Some((&0, &1, &mut 4.0)));
assert_eq!(iter.next(), Some((&1, &0, &mut 6.0)));
assert_eq!(iter.next(), Some((&1, &1, &mut 8.0)));
assert_eq!(iter.next(), None);

Trait Implementations

impl<T: Clone> Clone for CooMat<T>

fn clone(&self) -> CooMat<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for CooMat<T>

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

Formats the value using the given formatter.

impl<T> Extend<(usize, usize, T)> for CooMat<T>

fn extend<I: IntoIterator<Item = (usize, usize, T)>>(&mut self, iter: I)

Extend matrix entries.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let mut matrix: CooMat<f64> = CooMat::new(2, 2);
assert_eq!(matrix.len(), 0);
matrix.extend(entries);
assert_eq!(matrix.len(), 4);

pub fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

pub fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T> FromIterator<(usize, usize, T)> for CooMat<T>

fn from_iter<I: IntoIterator<Item = (usize, usize, T)>>(iter: I) -> Self

Collect entries into matrix.

Example

use sparse::CooMat;
let entries = vec![
    (0, 0, 1.0),
    (0, 1, 2.0),
    (1, 0, 3.0),
    (1, 1, 4.0),
];
let matrix: CooMat<f64> = entries.into_iter().collect();

impl<T> IntoIterator for CooMat<T>

type Item = (usize, usize, T)

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.