5 unstable releases
0.3.0 | Nov 13, 2022 |
---|---|
0.2.0 | Dec 6, 2021 |
0.1.2 | Feb 2, 2021 |
0.1.1 | Jan 17, 2021 |
0.1.0 | Jan 15, 2021 |
#30 in #stack-allocated
Used in 2 crates
13KB
vectrix
This crate provides a stack-allocated, constant-size Matrix<T, M, N>
type implemented using const generics.
🚀 Getting started
Add this crate to your Cargo manifest.
cargo add vectrix
no_std
is also supported by disabling the default std feature.
cargo add vectrix --no-default-features --features=macro
🤸 Usage
Types
The base Matrix<T, M, N>
type represents a matrix with M
rows and N
columns. This type is a backed by an array of arrays. The data is stored in
column-major order. Some convenient aliases are provided for common
matrices, like vectors.
Matrix<T, M, N>
→ a generic matrix type withM
rows andN
columns.Vector<T, M>
→ a column vector withM
rows.RowVector<T, N>
→ a row vector withN
columns.
Macros
Macros are provided for easy construction of the provided types. These
macros will also work in const
contexts.
-
The
matrix!
macro can be used to construct a newMatrix
of any size.let m = matrix![ 1, 3, 5; 2, 4, 6; ];
In the above example
matrix
is aMatrix<_, 2, 3>
type, having 2 rows and 3 columns. -
The
vector!
androw_vector!
macros can be used to to construct column and row vectors respectively.let v = vector![1, 3, 3, 7]; // ^ type `Vector<_, 4>` assert_eq!(v, matrix![1; 3; 3; 7]); let v = row_vector![1, 3, 3, 7]; // ^^^^^^ type `RowVector<_, 4>` assert_eq!(v, matrix![1, 3, 3, 7]);
Constructors
Commonly used constructors are listed below.
::zero()
→ constructs a new matrix filled withT::zero()
.::identity()
→ constructs a new identity matrix.::repeat(..)
→ constructs a new matrix filled with the provided value.::repeat_with(..)
→ constructs a new matrix filled with values computed by the provided closure.::from_iter(..)
→ constructs a new matrix from an iterator.::new(..)
→ constructs a new vector using the provided components.
Accessing elements
Three types of element access are available.
-
usize
indexing selects the nth element in the matrix as viewed in column-major order.let m = matrix![ 1, 2, 3; 4, 5, 6; ]; assert_eq!(m[1], 4);
-
(usize, usize)
indexing selects the element at a particular row and column position.let m = matrix![ 1, 2, 3; 4, 5, 6; ]; assert_eq!(m[(1, 0)], 4);
-
Component accessors are available for small vectors using traditional names.
let mut v = vector![1, 2, 3, 4, 0, 0]; v.y = 3; v.w = 7; assert_eq!(v.x, 1); assert_eq!(v.y, 3); assert_eq!(v.z, 3); assert_eq!(v.w, 7); assert_eq!(v.a, 0); assert_eq!(v.b, 0);
Accessing a row or column
You can get a reference to particular row or column using the
.row()
or .column()
methods. You
can get a mutable reference using the _mut
variants.
let mut m = matrix![
1, 2, 3;
4, 7, 6;
];
let row = m.row_mut(1);
row[1] = 5;
assert_eq!(m.column(1), &[2, 5]);
Iteration
Element-wise, column-major order iteration is provided using the following methods.
.into_iter()
→ consumes the matrix and returns an owned iterator over each element..iter()
→ returns an iterator over a reference to each element..iter_mut()
→ returns an iterator over a mutable reference to each element.
Iteration over rows and columns is provide using the following methods.
.iter_rows()
→ returns an iterator over a reference to each row..iter_rows_mut()
→ returns an iterator over mutable reference to each row..iter_columns()
→ returns an iterator over a reference to each column..iter_columns_mut()
→ returns an iterator over a mutable reference to each column.
Slice representation
A slice view of the underlying data is provided using
.as_slice()
and
.as_mut_slice()
.
let mut m = matrix![
1, 3, 5;
2, 3, 6;
];
m.as_mut_slice()[3] = 4;
assert_eq!(m.as_slice(), &[1, 2, 3, 4, 5, 6]);
Debug
The Debug
implementation will print out vectors as
lists and matrices as a list of lists in column-major order.
let v = vector![1.1, 2.0];
let m = matrix![1, 2; 3, 4];
println!("vector: {:.2?}", v);
println!("matrix: {:?}", m);
This will output:
vector: [1.10, 2.00]
matrix: [[1, 3], [2, 4]]
Display
The Display
implementation will print out the
matrix in the traditional box bracket format. Precision is supported as well
as most of the other formatting traits like
LowerHex
.
let cv = vector![1.1, 2.0];
let rv = row_vector![1.1, 2.0];
let m = matrix![1, 2; 3, 4];
println!("column vector: {:.2}", cv);
println!("row vector: {:.1}", rv);
println!("matrix: {:b}", m);
This will output:
column vector:
┌ ┐
│ 1.10 │
│ 2.00 │
└ ┘
row vector:
┌ ┐
│ 1.1 2.0 │
└ ┘
matrix:
┌ ┐
│ 1 10 │
│ 11 100 │
└ ┘
Operations
Matrix
implements many built-in operators. With scalar operands almost
all operators are implemented and they simply apply the operation to each
element in the matrix. Unary operators will do the equivalent. In the
following example each element in the matrix is multiplied by 2.
let m = matrix![
1, -3;
3, -7;
];
let exp = matrix![
2, -6;
6, -14;
];
assert_eq!(m * 2, exp);
Matrix
supports addition and subtraction with same size matrices for
element-wise addition and subtraction. In the following example a matrix
is added to itself.
let m = matrix![
1, -3;
3, -7;
];
let exp = matrix![
2, -6;
6, -14;
];
assert_eq!(m + m, exp);
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Dependencies
~1.5MB
~36K SLoC