Crate vectrix

This crate provides a stack-allocated, constant-size Matrix<T, M, N> type implemented using const generics.

🚀 Getting started

Add the following to your Cargo manifest.

[dependencies]
vectrix = "0.2"

no_std is also supported by disabling the default std feature.

[dependencies]
vectrix = { version = "0.2", default-features = false, 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 with M rows and N columns.
• Vector<T, M> → a column vector with M rows.
• RowVector<T, N> → a row vector with N 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 new Matrix of any size.

let matrix = matrix![
    1, 3, 5;
    2, 4, 6;
];

In the above example matrix is a Matrix<_, 2, 3> type, having 2 rows and 3 columns.

The vector! and row_vector! macros can be used to to construct vectors.

let vector = vector![1, 3, 3, 7];
//  ^^^^^^ type `Vector<_, 4>`
assert_eq!(vector, matrix![1; 3; 3; 7]);

let vector = row_vector![1, 3, 3, 7];
//  ^^^^^^ type `RowVector<_, 4>`
assert_eq!(vector, matrix![1, 3, 3, 7]);

Constructors

Commonly used constructors are listed below.

• ::zero() → constructs a new matrix filled with T::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

Two types of indexing is available:

Firstly, usize indexing which selects the nth element in the matrix as viewed in column-major order.

let matrix = matrix![
    1, 2, 3;
    4, 5, 6;
];
assert_eq!(matrix[1], 4);

Secondly, (usize, usize) indexing which selects the element at a particular row and column position.

let matrix = matrix![
    1, 2, 3;
    4, 5, 6;
];
assert_eq!(matrix[(1, 0)], 4);

Additionally, component accessors are available for small vectors using commonly recognized names.

let mut vector = vector![1, 2, 3, 4, 0, 0];
vector.y = 3;
vector.w = 7;
assert_eq!(vector.x, 1);
assert_eq!(vector.y, 3);
assert_eq!(vector.z, 3);
assert_eq!(vector.w, 7);
assert_eq!(vector.a, 0);
assert_eq!(vector.b, 0);

Accessing a row or column

You can get a reference to particular row or column using the .row() or .column() methods.

let mut matrix = matrix![
    1, 2, 3;
    4, 7, 6;
];
let row = matrix.row_mut(1);
row[1] = 5;
assert_eq!(matrix.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 matrix = matrix![
    1, 3, 5;
    2, 3, 6;
];
matrix.as_mut_slice()[3] = 4;
assert_eq!(matrix.as_slice(), &[1, 2, 3, 4, 5, 6]);

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 matrix = matrix![
    1, -3;
    3, -7;
];
let expected = matrix![
    2, -6;
    6, -14;
];
assert_eq!(matrix * 2, expected);

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 matrix = matrix![
    1, -3;
    3, -7;
];
let expected = matrix![
    2, -6;
    6, -14;
];
assert_eq!(matrix + matrix, expected);

Macros

matrix

A macro for composing matrices.

row_vector

A macro for composing row vectors.

vector

A macro for composing vectors.

Structs

Column

A column in a Matrix.

IntoIter

An iterator that moves out of a matrix.

IterColumns

An iterator over columns in a matrix.

IterColumnsMut

A mutable iterator over columns in a matrix.

IterRows

An iterator over rows in a matrix.

IterRowsMut

A mutable iterator over rows in a matrix.

Matrix

Represents a matrix with constant M rows and constant N columns.

Row

A row in a Matrix.

Traits

Abs

Defines the absolute value for a type.

MatrixIndex

A helper trait used for indexing operations.

One

Defines a multiplicative identity element for a type.

Zero

Defines a additive identity element for a type.

Type Definitions

RowVector

A matrix with one row and N columns.

Vector

A matrix with one column and M rows.