Struct aljabar::Matrix

#[repr(transparent)]pub struct Matrix<T, const N: usize, const M: usize>(_);

An N-by-M Column Major matrix.

Matrices can be created from arrays of Vectors of any size and scalar type. As with Vectors there are convenience constructor functions for square matrices of the most common sizes.

let a = Matrix::<f32, 3, 3>::from( [ vector!( 1.0, 0.0, 0.0 ),
                                     vector!( 0.0, 1.0, 0.0 ),
                                     vector!( 0.0, 0.0, 1.0 ), ] );
let b: Matrix::<i32, 3, 3> = matrix![
    [ 0, -3, 5 ],
    [ 6, 1, -4 ],
    [ 2, 3, -2 ]
];

All operations performed on matrices produce fixed-size outputs. For example, taking the transpose of a non-square matrix will produce a matrix with the width and height swapped:

assert_eq!(
    Matrix::<i32, 1, 2>::from( [ vector!( 1 ), vector!( 2 ) ] )
        .transpose(),
    Matrix::<i32, 2, 1>::from( [ vector!( 1, 2 ) ] )
);

Indexing

Matrices can be indexed by either their native column major storage or by the more natural row major method. In order to use row-major indexing, call .index or .index_mut on the matrix with a pair of indices. Calling .index with a single index will produce a vector representing the appropriate column of the matrix.

let m: Matrix::<i32, 2, 2> = matrix![
    [ 0, 2 ],
    [ 1, 3 ],
];

// Column-major indexing:
assert_eq!(m[0][0], 0);
assert_eq!(m[0][1], 1);
assert_eq!(m[1][0], 2);
assert_eq!(m[1][1], 3);

// Row-major indexing:
assert_eq!(m[(0, 0)], 0);
assert_eq!(m[(1, 0)], 1);
assert_eq!(m[(0, 1)], 2);
assert_eq!(m[(1, 1)], 3);

Iterating

Matrices are iterated most naturally over their columns, for which the following three functions are provided:

• column_iter, for immutably iterating over columns.
• column_iter_mut, for mutably iterating over columns.
• into_iter, for taking ownership of the columns.

Matrices can also be iterated over by their rows, however they can only be iterated over by RowViews, as they are not the natural storage for Matrices. The following functions are provided:

• row_iter, for immutably iterating over row views.
• row_iter_mut, for mutably iterating over row views (RowViewMut).
• In order to take ownership of the rows of the matrix, into_iter should called on the result of a transpose.

Implementations

impl<T, const N: usize, const M: usize> Matrix<T, { N }, { M }>

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

Swap the two given columns in-place.

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

Swap the two given rows in-place.

pub fn swap_elements(
    &mut self,
    (acol, arow): (usize, usize),
    (bcol, brow): (usize, usize)
)

Swap the two given elements at index a and index b.

The indices are expressed in the form (column, row), which may be confusing given the indexing strategy for matrices.

pub fn column_iter<'a>(&'a self) -> impl Iterator<Item = &'a Vector<T, { N }>>

Returns an immutable iterator over the columns of the matrix.

pub fn column_iter_mut<'a>(
    &'a mut self
) -> impl Iterator<Item = &'a mut Vector<T, { N }>>

Returns a mutable iterator over the columns of the matrix.

pub fn row_iter<'a>(
    &'a self
) -> impl Iterator<Item = RowView<'a, T, { N }, { M }>>

Returns an immutable iterator over the rows of the matrix.

pub fn row_iter_mut<'a>(
    &'a mut self
) -> impl Iterator<Item = RowViewMut<'a, T, { N }, { M }>>

Returns a mutable iterator over the rows of the matrix

pub fn map<Out, F>(self, f: F) -> Matrix<Out, { N }, { M }> where
    F: FnMut(T) -> Out, 

Applies the given function to each element of the matrix, constructing a new matrix with the returned outputs.

pub fn transpose(self) -> Matrix<T, { M }, { N }>

Returns the transpose of the matrix.

impl<T, const N: usize> Matrix<T, { N }, { N }> where
    T: Clone, 

pub fn diagonal(&self) -> Vector<T, { N }>

Return the diagonal of the matrix. Only available for square matrices.

impl<T, const N: usize> Matrix<T, { N }, { N }> where
    T: Clone + PartialOrd + Product + Real + One + Zero,
    T: Neg<Output = T>,
    T: Add<T, Output = T> + Sub<T, Output = T>,
    T: Mul<T, Output = T> + Div<T, Output = T>,
    Self: Add<Self>,
    Self: Sub<Self>,
    Self: Mul<Self>,
    Self: Mul<Vector<T, { N }>, Output = Vector<T, { N }>>, 

pub fn lu(self) -> Option<LU<T, { N }>>

Returns the LU decomposition of the matrix, if one exists.

pub fn determinant(&self) -> T

Returns the determinant of the matrix.

pub fn invert(self) -> Option<Self>

Attempt to invert the matrix. For square matrices greater in size than three, LU decomposition is guaranteed to be used.

Trait Implementations

impl<A, B, const N: usize, const M: usize> Add<Matrix<B, N, M>> for Matrix<A, { N }, { M }> where
    A: Add<B>, 

Element-wise addition of two equal sized matrices.

type Output = Matrix<<A as Add<B>>::Output, { N }, { M }>

The resulting type after applying the + operator.

fn add(self, rhs: Matrix<B, { N }, { M }>) -> Self::Output

Performs the + operation.

impl<A, B, const N: usize, const M: usize> AddAssign<Matrix<B, N, M>> for Matrix<A, { N }, { M }> where
    A: AddAssign<B>, 

fn add_assign(&mut self, rhs: Matrix<B, { N }, { M }>)

Performs the += operation.

impl<T, const N: usize, const M: usize> Clone for Matrix<T, { N }, { M }> where
    T: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, const N: usize, const M: usize> Copy for Matrix<T, { N }, { M }> where
    T: Copy, 

impl<T, const N: usize, const M: usize> Debug for Matrix<T, { N }, { M }> where
    T: Debug, 

I'm not quite sure how to format the debug output for a matrix.

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

Formats the value using the given formatter.

impl<T, const N: usize, const M: usize> Deref for Matrix<T, { N }, { M }>

type Target = [Vector<T, { N }>; M]

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T, const N: usize, const M: usize> DerefMut for Matrix<T, { N }, { M }>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'de, T, const N: usize, const M: usize> Deserialize<'de> for Matrix<T, { N }, { M }> where
    T: Deserialize<'de>, 

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

Deserialize this value from the given Serde deserializer.

impl<T, const N: usize, const M: usize> Distribution<Matrix<T, N, M>> for Standard where
    Standard: Distribution<Vector<T, { N }>>, 

fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> Matrix<T, { N }, { M }>

Generate a random value of T, using rng as the source of randomness.

fn sample_iter<R>(self, rng: R) -> DistIter<Self, R, T> where
    R: Rng, 

Create an iterator that generates random values of T, using rng as the source of randomness.

impl<T, const N: usize, const M: usize> From<[[T; N]; M]> for Matrix<T, { N }, { M }>

fn from(array: [[T; N]; M]) -> Self

Performs the conversion.

impl<T, const N: usize, const M: usize> From<[Vector<T, N>; M]> for Matrix<T, { N }, { M }>

fn from(array: [Vector<T, { N }>; M]) -> Self

Performs the conversion.

impl<T, const N: usize> From<Matrix<T, N, 1_usize>> for Vector<T, { N }>

fn from(mat: Matrix<T, { N }, 1>) -> Self

Performs the conversion.

impl<T, const N: usize, const M: usize> FromIterator<T> for Matrix<T, { N }, { M }>

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

Creates a value from an iterator.

impl<T, const N: usize, const M: usize> FromIterator<Vector<T, N>> for Matrix<T, { N }, { M }>

fn from_iter<I>(iter: I) -> Self where
    I: IntoIterator<Item = Vector<T, { N }>>, 

Creates a value from an iterator.

impl<T, const N: usize, const M: usize> Hash for Matrix<T, { N }, { M }> where
    T: Hash, 

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<T, const N: usize, const M: usize> Index<(usize, usize)> for Matrix<T, { N }, { M }>

type Output = T

The returned type after indexing.

fn index(&self, (row, column): (usize, usize)) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, const N: usize, const M: usize> Index<usize> for Matrix<T, { N }, { M }>

type Output = Vector<T, { N }>

The returned type after indexing.

fn index(&self, column: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<T, const N: usize, const M: usize> IndexMut<(usize, usize)> for Matrix<T, { N }, { M }>

fn index_mut(&mut self, (row, column): (usize, usize)) -> &mut Self::Output

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

impl<T, const N: usize, const M: usize> IndexMut<usize> for Matrix<T, { N }, { M }>

fn index_mut(&mut self, column: usize) -> &mut Self::Output

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

impl<T, const N: usize, const M: usize> IntoIterator for Matrix<T, { N }, { M }>

type Item = Vector<T, { N }>

The type of the elements being iterated over.

type IntoIter = ArrayIter<Vector<T, { N }>, { M }>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T, const N: usize, const M: usize, const P: usize> Mul<Matrix<T, M, P>> for Matrix<T, { N }, { M }> where
    T: Add<T, Output = T> + Mul<T, Output = T> + Clone,
    Vector<T, { M }>: InnerSpace, 

type Output = Matrix<<Vector<T, { M }> as VectorSpace>::Scalar, { N }, { P }>

The resulting type after applying the * operator.

fn mul(self, rhs: Matrix<T, { M }, { P }>) -> Self::Output

Performs the * operation.

impl<const N: usize, const M: usize> Mul<Matrix<f32, N, M>> for f32

type Output = Matrix<f32, { N }, { M }>

The resulting type after applying the * operator.

fn mul(self, mat: Matrix<f32, { N }, { M }>) -> Self::Output

Performs the * operation.

impl<const N: usize, const M: usize> Mul<Matrix<f64, N, M>> for f64

type Output = Matrix<f64, { N }, { M }>

The resulting type after applying the * operator.

fn mul(self, mat: Matrix<f64, { N }, { M }>) -> Self::Output

Performs the * operation.

impl<T, const N: usize, const M: usize> Mul<T> for Matrix<T, { N }, { M }> where
    T: Mul<T, Output = T> + Clone, 

Scalar multiply

type Output = Matrix<T, { N }, { M }>

The resulting type after applying the * operator.

fn mul(self, scalar: T) -> Self::Output

Performs the * operation.

impl<T, const N: usize, const M: usize> Mul<Vector<T, M>> for Matrix<T, { N }, { M }> where
    T: Add<T, Output = T> + Mul<T, Output = T> + Clone,
    Vector<T, { M }>: InnerSpace, 

type Output = Vector<<Vector<T, { M }> as VectorSpace>::Scalar, { N }>

The resulting type after applying the * operator.

fn mul(self, rhs: Vector<T, { M }>) -> Self::Output

Performs the * operation.

impl<T, const N: usize, const M: usize> Neg for Matrix<T, { N }, { M }> where
    T: Neg, 

type Output = Matrix<<T as Neg>::Output, { N }, { M }>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T, const N: usize> One for Matrix<T, { N }, { N }> where
    T: Zero + One + Clone,
    Self: PartialEq<Self>, 

Constructs a unit matrix.

fn one() -> Self

Returns the multiplicative identity for Self.

fn is_one(&self) -> bool

Returns true if the value is the multiplicative identity.

impl<A, B, RHS, const N: usize, const M: usize> PartialEq<RHS> for Matrix<A, { N }, { M }> where
    RHS: Deref<Target = [Vector<B, { N }>; M]>,
    A: PartialEq<B>, 

fn eq(&self, other: &RHS) -> bool

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T, const N: usize, const M: usize> Serialize for Matrix<T, { N }, { M }> where
    Vector<T, { N }>: Serialize, 

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

Serialize this value into the given Serde serializer.

impl<A, B, const N: usize, const M: usize> Sub<Matrix<B, N, M>> for Matrix<A, { N }, { M }> where
    A: Sub<B>, 

Element-wise subtraction of two equal sized matrices.

type Output = Matrix<<A as Sub<B>>::Output, { N }, { M }>

The resulting type after applying the - operator.

fn sub(self, rhs: Matrix<B, { N }, { M }>) -> Self::Output

Performs the - operation.

impl<A, B, const N: usize, const M: usize> SubAssign<Matrix<B, N, M>> for Matrix<A, { N }, { M }> where
    A: SubAssign<B>, 

fn sub_assign(&mut self, rhs: Matrix<B, { N }, { M }>)

Performs the -= operation.

impl<T, const N: usize, const M: usize> Zero for Matrix<T, { N }, { M }> where
    T: Zero,
    Vector<T, { N }>: Zero, 

fn zero() -> Self

Returns the additive identity of Self.

fn is_zero(&self) -> bool

Returns true if the value is the additive identity.