Struct faer_core::MatRef

pub struct MatRef<'a, T> { /* private fields */ }

Matrix view with general row and column strides.

Implementations

impl<'a, T> MatRef<'a, T>

pub unsafe fn from_raw_parts(
    ptr: *const T,
    nrows: usize,
    ncols: usize,
    row_stride: isize,
    col_stride: isize
) -> Self

Returns a matrix slice from the given arguments.
ptr: pointer to the first element of the matrix.
nrows: number of rows of the matrix.
ncols: number of columns of the matrix.
row_stride: offset between the first elements of two successive rows in the matrix. col_stride: offset between the first elements of two successive columns in the matrix.

Safety

ptr must be non null and properly aligned for type T.
For each i < nrows and j < ncols,
ptr.offset(i as isize * row_stride + j as isize * col_stride) must point to a valid initialized object of type T, unless memory pointing to that address is never accessed.
The referenced memory must not be mutated during the lifetime 'a.

Example

use faer_core::MatRef;

let nan = f64::NAN;
let data = vec![0.0, 1.0, nan, 2.0, 3.0, nan, 4.0, 5.0];

let nrows = 2;
let ncols = 3;
let row_stride = 1;
let col_stride = 3;
let m = unsafe { MatRef::from_raw_parts(data.as_ptr(), nrows, ncols, row_stride, col_stride) };

assert_eq!(m.nrows(), 2);
assert_eq!(m.ncols(), 3);

assert_eq!(m[(0, 0)], 0.0);
assert_eq!(m[(1, 0)], 1.0);
assert_eq!(m[(0, 1)], 2.0);
assert_eq!(m[(1, 1)], 3.0);
assert_eq!(m[(0, 2)], 4.0);
assert_eq!(m[(1, 2)], 5.0);

pub fn as_ptr(self) -> *const T

Returns a pointer to the first (top left) element of the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert_eq!(unsafe { *m.as_ptr() }, 0.0);

pub fn nrows(&self) -> usize

Returns the number of rows of the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert_eq!(m.nrows(), 2);

pub fn ncols(&self) -> usize

Returns the number of columns of the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert_eq!(m.ncols(), 3);

pub fn row_stride(&self) -> isize

Returns the offset between the first elements of two successive rows in the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert_eq!(m.row_stride(), 1); // mat! returns a column major matrix

pub fn col_stride(&self) -> isize

Returns the offset between the first elements of two successive columns in the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert!(m.col_stride() >= 2); // the stride has to be at least 2, since the matrix is
                              // column major and each column has 2 elements.

pub fn ptr_at(self, i: usize, j: usize) -> *const T

Returns a pointer to the element at position (i, j) in the matrix.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();

assert_eq!(unsafe { *m.ptr_at(1, 2) }, 5.0);

pub unsafe fn ptr_in_bounds_at_unchecked(self, i: usize, j: usize) -> *const T

Returns a pointer to the element at position (i, j) in the matrix, assuming it falls within its bounds with no bound checks.

Safety

Requires that i < self.nrows() and j < self.ncols().

Otherwise, the behavior is undefined.

Example

See Self::ptr_at.

pub fn ptr_in_bounds_at(self, i: usize, j: usize) -> *const T

Returns a pointer to the element at position (i, j) in the matrix, while asserting that it falls within its bounds.

Panics

Requires that i < self.nrows() and j < self.ncols().

Otherwise, it panics.

Example

See Self::ptr_at.

pub unsafe fn split_at_unchecked(
    self,
    i: usize,
    j: usize
) -> (Self, Self, Self, Self)

Splits the matrix into four corner parts in the following order: top left, top right, bottom left, bottom right.

Safety

Requires that i <= self.nrows() and j <= self.ncols().

Otherwise, the behavior is undefined.

Example

See Self::split_at.

pub fn split_at(self, i: usize, j: usize) -> (Self, Self, Self, Self)

Splits the matrix into four corner parts in the following order: top left, top right, bottom left, bottom right.

Panics

Requires that i <= self.nrows() and j <= self.ncols().

Otherwise, it panics.

Example

use faer_core::mat;

let m = mat![[0.0, 2.0, 4.0], [1.0, 3.0, 5.0]];
let m = m.as_ref();
let (top_left, top_right, bot_left, bot_right) = m.split_at(1, 1);

assert_eq!(top_left.nrows(), 1);
assert_eq!(top_left.ncols(), 1);
assert_eq!(top_left[(0, 0)], 0.0);

assert_eq!(top_right.nrows(), 1);
assert_eq!(top_right.ncols(), 2);
assert_eq!(top_right[(0, 0)], 2.0);
assert_eq!(top_right[(0, 1)], 4.0);

assert_eq!(bot_left.nrows(), 1);
assert_eq!(bot_left.ncols(), 1);
assert_eq!(bot_left[(0, 0)], 1.0);

assert_eq!(bot_right.nrows(), 1);
assert_eq!(bot_right.ncols(), 2);
assert_eq!(bot_right[(0, 0)], 3.0);
assert_eq!(bot_right[(0, 1)], 5.0);

pub unsafe fn get_unchecked(self, i: usize, j: usize) -> &'a T

Returns a reference to the element at position (i, j), with no bound checks.

Safety

Requires that i < self.nrows() and j < self.ncols().

Otherwise, the behavior is undefined.

Example

See Self::get.

pub fn get(self, i: usize, j: usize) -> &'a T

Returns a reference to the element at position (i, j), or panics if the indices are out of bounds.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

assert_eq!(m.get(1, 2), &7.0);

pub unsafe fn row_unchecked(self, i: usize) -> RowRef<'a, T>

Returns the i-th row of the matrix, with no bound checks.

Safety

Requires that i < self.nrows().

Otherwise, the behavior is undefined.

Example

See Self::row.

pub fn row(self, i: usize) -> RowRef<'a, T>

Returns the i-th row of the matrix.

Panics

Requires that i < self.nrows().

Otherwise, it panics.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let r = m.row(1);

assert_eq!(r[2], 7.0);

pub unsafe fn col_unchecked(self, j: usize) -> ColRef<'a, T>

Returns the j-th column of the matrix, with no bound checks.

Safety

Requires that j < self.ncols().

Otherwise, the behavior is undefined.

Example

See Self::col.

pub fn col(self, j: usize) -> ColRef<'a, T>

Returns the j-th column of the matrix.

Panics

Requires that j < self.ncols().

Otherwise, it panics.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let c = m.col(1);

assert_eq!(c[2], 5.0);

pub fn transpose(self) -> MatRef<'a, T>

Returns the transpose of self.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let t = m.transpose();

assert_eq!(t.nrows(), m.ncols());
assert_eq!(t.ncols(), m.nrows());

assert_eq!(t[(0, 0)], m[(0, 0)]);
assert_eq!(t[(1, 0)], m[(0, 1)]);
assert_eq!(t[(2, 0)], m[(0, 2)]);
assert_eq!(t[(3, 0)], m[(0, 3)]);

assert_eq!(t[(0, 1)], m[(1, 0)]);
assert_eq!(t[(1, 1)], m[(1, 1)]);
assert_eq!(t[(2, 1)], m[(1, 2)]);
assert_eq!(t[(3, 1)], m[(1, 3)]);

assert_eq!(t[(0, 2)], m[(2, 0)]);
assert_eq!(t[(1, 2)], m[(2, 1)]);
assert_eq!(t[(2, 2)], m[(2, 2)]);
assert_eq!(t[(3, 2)], m[(2, 3)]);

pub fn reverse_rows(self) -> Self

Returns a matrix whose rows are the the rows of the input matrix in reverse order.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let i = m.reverse_rows();

assert_eq!(i.nrows(), m.nrows());
assert_eq!(i.ncols(), m.ncols());

assert_eq!(i[(0, 0)], m[(2, 0)]);
assert_eq!(i[(1, 0)], m[(1, 0)]);
assert_eq!(i[(2, 0)], m[(0, 0)]);

assert_eq!(i[(0, 1)], m[(2, 1)]);
assert_eq!(i[(1, 1)], m[(1, 1)]);
assert_eq!(i[(2, 1)], m[(0, 1)]);

assert_eq!(i[(0, 2)], m[(2, 2)]);
assert_eq!(i[(1, 2)], m[(1, 2)]);
assert_eq!(i[(2, 2)], m[(0, 2)]);

assert_eq!(i[(0, 3)], m[(2, 3)]);
assert_eq!(i[(1, 3)], m[(1, 3)]);
assert_eq!(i[(2, 3)], m[(0, 3)]);

pub fn reverse_cols(self) -> Self

Returns a matrix whose columns are the the columns of the input matrix in reverse order.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let i = m.reverse_cols();

assert_eq!(i.nrows(), m.nrows());
assert_eq!(i.ncols(), m.ncols());

assert_eq!(i[(0, 0)], m[(0, 3)]);
assert_eq!(i[(1, 0)], m[(1, 3)]);
assert_eq!(i[(2, 0)], m[(2, 3)]);

assert_eq!(i[(0, 1)], m[(0, 2)]);
assert_eq!(i[(1, 1)], m[(1, 2)]);
assert_eq!(i[(2, 1)], m[(2, 2)]);

assert_eq!(i[(0, 2)], m[(0, 1)]);
assert_eq!(i[(1, 2)], m[(1, 1)]);
assert_eq!(i[(2, 2)], m[(2, 1)]);

assert_eq!(i[(0, 3)], m[(0, 0)]);
assert_eq!(i[(1, 3)], m[(1, 0)]);
assert_eq!(i[(2, 3)], m[(2, 0)]);

pub fn reverse_rows_and_cols(self) -> Self

Returns a matrix whose rows and columns are the the rows and columns of the input matrix in reverse order.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let i = m.reverse_rows_and_cols();

assert_eq!(i.nrows(), m.nrows());
assert_eq!(i.ncols(), m.ncols());

assert_eq!(i[(0, 0)], m[(2, 3)]);
assert_eq!(i[(1, 0)], m[(1, 3)]);
assert_eq!(i[(2, 0)], m[(0, 3)]);

assert_eq!(i[(0, 1)], m[(2, 2)]);
assert_eq!(i[(1, 1)], m[(1, 2)]);
assert_eq!(i[(2, 1)], m[(0, 2)]);

assert_eq!(i[(0, 2)], m[(2, 1)]);
assert_eq!(i[(1, 2)], m[(1, 1)]);
assert_eq!(i[(2, 2)], m[(0, 1)]);

assert_eq!(i[(0, 3)], m[(2, 0)]);
assert_eq!(i[(1, 3)], m[(1, 0)]);
assert_eq!(i[(2, 3)], m[(0, 0)]);

pub unsafe fn diagonal_unchecked(self) -> ColRef<'a, T>

Returns the diagonal of the matrix, as a column vector.

Safety

Requires that the matrix be square.

Otherwise, the behavior is undefined.

Example

See Self::diagonal.

pub fn diagonal(self) -> ColRef<'a, T>

Returns the diagonal of the matrix, as a column vector.

Panics

Requires that the matrix be square.

Otherwise, it panics.

Example

use faer_core::mat;

let m = mat![[0.0, 3.0, 6.0], [1.0, 4.0, 7.0], [2.0, 5.0, 8.0]];
let m = m.as_ref();

let d = m.diagonal();

assert_eq!(d.nrows(), 3);
assert_eq!(d.ncols(), 1);

assert_eq!(d[0], 0.0);
assert_eq!(d[1], 4.0);
assert_eq!(d[2], 8.0);

pub fn into_row_iter(self) -> RowIter<'a, T>

Returns an iterator over the rows of the matrix.

pub fn into_col_iter(self) -> ColIter<'a, T>

Returns an iterator over the columns of the matrix.

pub unsafe fn submatrix_unchecked(
    self,
    i: usize,
    j: usize,
    nrows: usize,
    ncols: usize
) -> Self

Returns a view over a submatrix of self, starting at position (i, j) with dimensions (nrows, ncols).

Safety

Requires that i <= self.nrows(),
j <= self.ncols(),
nrows <= self.nrows() - i
and ncols <= self.ncols() - j.

Otherwise, the behavior is undefined.

Example

See Self::submatrix.

pub fn submatrix(self, i: usize, j: usize, nrows: usize, ncols: usize) -> Self

Returns a view over a submatrix of self, starting at position (i, j) with dimensions (nrows, ncols).

Panics

Requires that i <= self.nrows(),
j <= self.ncols(),
nrows <= self.nrows() - i
and ncols <= self.ncols() - j.

Otherwise, it panics.

Example

use faer_core::mat;

let m = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let m = m.as_ref();

let sub = m.submatrix(1, 2, 2, 2);

assert_eq!(sub.nrows(), 2);
assert_eq!(sub.ncols(), 2);

assert_eq!(sub[(0, 0)], 7.0);
assert_eq!(sub[(1, 0)], 8.0);
assert_eq!(sub[(0, 1)], 10.0);
assert_eq!(sub[(1, 1)], 11.0);

pub fn cwise(self) -> ZipMat<(Self,)>

Returns a thin wrapper that can be used to execute coefficientwise operations on matrices.

Example

use faer_core::mat;
use reborrow::*;

let a = mat![
    [0.0, 3.0, 6.0, 9.0],
    [1.0, 4.0, 7.0, 10.0],
    [2.0, 5.0, 8.0, 11.0],
];
let b = mat![
    [12.0, 15.0, 18.0, 21.0],
    [13.0, 16.0, 19.0, 22.0],
    [14.0, 17.0, 20.0, 23.0],
];
let mut c = mat![
    [0.0, 0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0, 0.0],
    [0.0, 0.0, 0.0, 0.0],
];

let a = a.as_ref();
let b = b.as_ref();
let mut c = c.as_mut();

c.rb_mut()
    .cwise()
    .zip(a)
    .zip(b)
    .for_each(|c, a, b| *c = *a + *b);

assert_eq!(c[(0, 0)], a[(0, 0)] + b[(0, 0)]);
assert_eq!(c[(1, 0)], a[(1, 0)] + b[(1, 0)]);
assert_eq!(c[(2, 0)], a[(2, 0)] + b[(2, 0)]);

assert_eq!(c[(0, 1)], a[(0, 1)] + b[(0, 1)]);
assert_eq!(c[(1, 1)], a[(1, 1)] + b[(1, 1)]);
assert_eq!(c[(2, 1)], a[(2, 1)] + b[(2, 1)]);

assert_eq!(c[(0, 2)], a[(0, 2)] + b[(0, 2)]);
assert_eq!(c[(1, 2)], a[(1, 2)] + b[(1, 2)]);
assert_eq!(c[(2, 2)], a[(2, 2)] + b[(2, 2)]);

assert_eq!(c[(0, 3)], a[(0, 3)] + b[(0, 3)]);
assert_eq!(c[(1, 3)], a[(1, 3)] + b[(1, 3)]);
assert_eq!(c[(2, 3)], a[(2, 3)] + b[(2, 3)]);

impl<'a, T> MatRef<'a, Complex<T>>

pub fn into_real_imag(self) -> (MatRef<'a, T>, MatRef<'a, T>)

Trait Implementations

impl<'a, T> Clone for MatRef<'a, T>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'short, 'a, T> CwiseMat<'short, &'short MatRef<'a, T>> for MatRef<'a, T>

type Item = &'short T

fn nrows(&self) -> usize

fn ncols(&self) -> usize

fn is_col_major(&self) -> bool

fn is_row_major(&self) -> bool

unsafe fn get_unchecked(&'short mut self, i: usize, j: usize) -> Self::Item

unsafe fn get_col_major_unchecked(
    &'short mut self,
    i: usize,
    j: usize
) -> Self::Item

unsafe fn get_row_major_unchecked(
    &'short mut self,
    i: usize,
    j: usize
) -> Self::Item

fn transpose(self) -> Self

impl<'a, T: Debug + 'static> Debug for MatRef<'a, T>

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

Formats the value using the given formatter.

impl<'a, T> Index<(usize, usize)> for MatRef<'a, T>

type Output = T

The returned type after indexing.

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

Performs the indexing (container[index]) operation.

impl<'a, T> IntoConst for MatRef<'a, T>

type Target = MatRef<'a, T>

fn into_const(self) -> Self::Target

impl<'b, 'a, T> Reborrow<'b, &'b MatRef<'a, T>> for MatRef<'a, T>

type Target = MatRef<'b, T>

fn rb(&'b self) -> Self::Target

impl<'b, 'a, T> ReborrowMut<'b, &'b MatRef<'a, T>> for MatRef<'a, T>

type Target = MatRef<'b, T>

fn rb_mut(&'b mut self) -> Self::Target

impl<'a, T> Copy for MatRef<'a, T>

impl<'a, T: Sync> Send for MatRef<'a, T>

impl<'a, T: Sync> Sync for MatRef<'a, T>