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

#1004 in Procedural macros

43 downloads per month
Used in 2 crates

MIT/Apache

13KB

vectrix

Crates.io Version Docs.rs Latest Build Status

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.

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 m = 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 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 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

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.

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

at your option.

Dependencies

~1.5MB
~34K SLoC