1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
//! Submodule defining the `MatrixMut` trait.
use super::{Matrix, SparseMatrix};
/// Trait defining a mutable matrix.
pub trait MatrixMut: Matrix + Default {
/// Type of the entry of the matrix.
/// In a matrix with values, this is generally a tuple of the coordinates
/// and the value, while in a matrix without values, this is generally
/// the coordinates.
type Entry;
/// The type of error that can be returned when adding an entry.
type Error: core::error::Error;
/// Sets the value at the given entry.
///
/// # Arguments
///
/// * `entry`: The entry to set.
///
/// # Errors
///
/// Returns an error if the entry cannot be added. Possible reasons include:
/// - The entries are not provided in the expected order.
/// - The entry is out of bounds.
/// - The entry is already defined.
fn add(&mut self, entry: Self::Entry) -> Result<(), Self::Error>;
/// Creates a new matrix with the given entries.
///
/// # Arguments
///
/// * `entries` - The entries to add to the matrix.
///
/// # Errors
///
/// * If the entries are not provided in the expected order.
/// * If the entry is out of bounds.
/// * If the entry is already defined.
#[inline]
fn from_entries<I: IntoIterator<Item = Self::Entry>>(entries: I) -> Result<Self, Self::Error> {
let mut matrix = Self::default();
matrix.extend(entries)?;
Ok(matrix)
}
/// Extends the matrix with the given entries.
///
/// # Arguments
///
/// * `entries` - The entries to add to the matrix.
///
/// # Errors
///
/// * If the entries are not provided in the expected order.
/// * If the entry is out of bounds.
/// * If the entry is already defined.
#[inline]
fn extend<I: IntoIterator<Item = Self::Entry>>(
&mut self,
entries: I,
) -> Result<(), Self::Error> {
for entry in entries {
self.add(entry)?;
}
Ok(())
}
/// Set the matrix to the given larger shape.
///
/// # Arguments
///
/// * `shape` - The larger shape of the matrix.
///
/// # Errors
///
/// * If the shape is smaller than the current shape.
fn increase_shape(&mut self, shape: Self::Coordinates) -> Result<(), Self::Error>;
}
/// Trait defining a bi-dimensional mutable matrix.
pub trait SparseMatrixMut: MatrixMut + SparseMatrix {
/// Type describing the shape of the matrix.
type MinimalShape: core::fmt::Debug + Copy;
/// Creates a new matrix with the given capacity, using the given shape.
///
/// # Arguments
///
/// * `shape` - The shape of the matrix.
/// * `number_of_values` - The number of values.
fn with_sparse_shaped_capacity(
shape: Self::MinimalShape,
number_of_values: Self::SparseIndex,
) -> Self;
/// Creates a new matrix with the given shape.
///
/// # Arguments
///
/// * `shape` - The shape of the matrix.
fn with_sparse_shape(shape: Self::MinimalShape) -> Self;
/// Creates a new matrix with the given capacity and unknown shape.
///
/// # Arguments
///
/// * `number_of_values` - The number of values.
fn with_sparse_capacity(number_of_values: Self::SparseIndex) -> Self;
}