pub type MatMut<'a, E> = Matrix<DenseMut<'a, E>>;Expand description
Mutable view over a matrix, similar to a mutable reference to a 2D strided slice.
Note
Unlike a slice, the data pointed to by MatMut<'_, E> is allowed to be partially or fully
uninitialized under certain conditions. In this case, care must be taken to not perform any
operations that read the uninitialized values, or form references to them, either directly
through MatMut::read, or indirectly through any of the numerical library routines, unless
it is explicitly permitted.
Move semantics
Since MatMut mutably borrows data, it cannot be Copy. This means that if we pass a
MatMut to a function that takes it by value, or use a method that consumes self like
MatMut::transpose, this renders the original variable unusable.
use faer_core::{Mat, MatMut};
fn takes_matmut(view: MatMut<'_, f64>) {}
let mut matrix = Mat::new();
let view = matrix.as_mut();
takes_matmut(view); // `view` is moved (passed by value)
takes_matmut(view); // this fails to compile since `view` was movedThe way to get around it is to use the reborrow::ReborrowMut trait, which allows us to
mutably borrow a MatMut to obtain another MatMut for the lifetime of the borrow.
It’s also similarly possible to immutably borrow a MatMut to obtain a MatRef for the
lifetime of the borrow, using reborrow::Reborrow.
use faer_core::{Mat, MatMut, MatRef};
use reborrow::*;
fn takes_matmut(view: MatMut<'_, f64>) {}
fn takes_matref(view: MatRef<'_, f64>) {}
let mut matrix = Mat::new();
let mut view = matrix.as_mut();
takes_matmut(view.rb_mut());
takes_matmut(view.rb_mut());
takes_matref(view.rb());
// view is still usable hereAliased Type§
struct MatMut<'a, E> { /* private fields */ }Implementations§
source§impl<'a, E: Entity> MatMut<'a, E>
impl<'a, E: Entity> MatMut<'a, E>
pub fn from_column_major_slice( slice: GroupFor<E, &'a mut [E::Unit]>, nrows: usize, ncols: usize ) -> Self
faer_core::mat::from_column_major_slice_mutpub fn from_row_major_slice( slice: GroupFor<E, &'a mut [E::Unit]>, nrows: usize, ncols: usize ) -> Self
faer_core::mat::from_row_major_slice_mutpub unsafe fn from_raw_parts( ptr: GroupFor<E, *mut E::Unit>, nrows: usize, ncols: usize, row_stride: isize, col_stride: isize ) -> Self
faer_core::mat::from_raw_parts_mutpub fn nrows(&self) -> usize
pub fn ncols(&self) -> usize
sourcepub fn as_ptr_mut(self) -> GroupFor<E, *mut E::Unit>
pub fn as_ptr_mut(self) -> GroupFor<E, *mut E::Unit>
Returns pointers to the matrix data.
pub fn as_ptr(self) -> GroupFor<E, *mut E::Unit>
MatMut::as_ptr_mutsourcepub fn row_stride(&self) -> isize
pub fn row_stride(&self) -> isize
Returns the row stride of the matrix, specified in number of elements, not in bytes.
sourcepub fn col_stride(&self) -> isize
pub fn col_stride(&self) -> isize
Returns the column stride of the matrix, specified in number of elements, not in bytes.
sourcepub fn ptr_at_mut(self, row: usize, col: usize) -> GroupFor<E, *mut E::Unit>
pub fn ptr_at_mut(self, row: usize, col: usize) -> GroupFor<E, *mut E::Unit>
Returns raw pointers to the element at the given indices.
pub fn ptr_at(self, row: usize, col: usize) -> GroupFor<E, *mut E::Unit>
MatMut::ptr_at_mutsourcepub unsafe fn ptr_inbounds_at_mut(
self,
row: usize,
col: usize
) -> GroupFor<E, *mut E::Unit>
pub unsafe fn ptr_inbounds_at_mut( self, row: usize, col: usize ) -> GroupFor<E, *mut E::Unit>
Returns raw pointers to the element at the given indices, assuming the provided indices are within the matrix dimensions.
Safety
The behavior is undefined if any of the following conditions are violated:
row < self.nrows().col < self.ncols().
pub unsafe fn ptr_inbounds_at( self, row: usize, col: usize ) -> GroupFor<E, *mut E::Unit>
MatMut::ptr_inbounds_at_mutsourcepub unsafe fn split_at_mut_unchecked(
self,
row: usize,
col: usize
) -> (Self, Self, Self, Self)
pub unsafe fn split_at_mut_unchecked( self, row: usize, col: usize ) -> (Self, Self, Self, Self)
Splits the matrix horizontally and vertically at the given indices into four corners and returns an array of each submatrix, in the following order:
- top left.
- top right.
- bottom left.
- bottom right.
Safety
The behavior is undefined if any of the following conditions are violated:
row <= self.nrows().col <= self.ncols().
sourcepub fn split_at_mut(self, row: usize, col: usize) -> (Self, Self, Self, Self)
pub fn split_at_mut(self, row: usize, col: usize) -> (Self, Self, Self, Self)
Splits the matrix horizontally and vertically at the given indices into four corners and returns an array of each submatrix, in the following order:
- top left.
- top right.
- bottom left.
- bottom right.
Panics
The function panics if any of the following conditions are violated:
row <= self.nrows().col <= self.ncols().
sourcepub unsafe fn split_at_row_mut_unchecked(self, row: usize) -> (Self, Self)
pub unsafe fn split_at_row_mut_unchecked(self, row: usize) -> (Self, Self)
Splits the matrix horizontally at the given row into two parts and returns an array of each submatrix, in the following order:
- top.
- bottom.
Safety
The behavior is undefined if the following condition is violated:
row <= self.nrows().
sourcepub fn split_at_row_mut(self, row: usize) -> (Self, Self)
pub fn split_at_row_mut(self, row: usize) -> (Self, Self)
Splits the matrix horizontally at the given row into two parts and returns an array of each submatrix, in the following order:
- top.
- bottom.
Panics
The function panics if the following condition is violated:
row <= self.nrows().
sourcepub unsafe fn split_at_col_mut_unchecked(self, col: usize) -> (Self, Self)
pub unsafe fn split_at_col_mut_unchecked(self, col: usize) -> (Self, Self)
Splits the matrix vertically at the given row into two parts and returns an array of each submatrix, in the following order:
- left.
- right.
Safety
The behavior is undefined if the following condition is violated:
col <= self.ncols().
sourcepub fn split_at_col_mut(self, col: usize) -> (Self, Self)
pub fn split_at_col_mut(self, col: usize) -> (Self, Self)
Splits the matrix vertically at the given row into two parts and returns an array of each submatrix, in the following order:
- left.
- right.
Panics
The function panics if the following condition is violated:
col <= self.ncols().
pub fn split_at(self, row: usize, col: usize) -> (Self, Self, Self, Self)
MatMut::split_at_mutpub fn split_at_row(self, row: usize) -> (Self, Self)
MatMut::split_at_row_mutpub fn split_at_col(self, col: usize) -> (Self, Self)
MatMut::split_at_col_mutsourcepub unsafe fn get_mut_unchecked<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
pub unsafe fn get_mut_unchecked<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
Returns mutable references to the element at the given indices, or submatrices if either
row or col is a range.
Note
The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.
Safety
The behavior is undefined if any of the following conditions are violated:
rowmust be contained in[0, self.nrows()).colmust be contained in[0, self.ncols()).
pub unsafe fn get_unchecked<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
MatMut::get_mut_uncheckedsourcepub fn get_mut<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
pub fn get_mut<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
Returns mutable references to the element at the given indices, or submatrices if either
row or col is a range, with bound checks.
Note
The values pointed to by the references are expected to be initialized, even if the pointed-to value is not read, otherwise the behavior is undefined.
Panics
The function panics if any of the following conditions are violated:
rowmust be contained in[0, self.nrows()).colmust be contained in[0, self.ncols()).
pub fn get<RowRange, ColRange>(
self,
row: RowRange,
col: ColRange
) -> <Self as MatIndex<RowRange, ColRange>>::Targetwhere
Self: MatIndex<RowRange, ColRange>,
MatMut::get_mutsourcepub unsafe fn read_unchecked(&self, row: usize, col: usize) -> E
pub unsafe fn read_unchecked(&self, row: usize, col: usize) -> E
Reads the value of the element at the given indices.
Safety
The behavior is undefined if any of the following conditions are violated:
row < self.nrows().col < self.ncols().
sourcepub fn read(&self, row: usize, col: usize) -> E
pub fn read(&self, row: usize, col: usize) -> E
Reads the value of the element at the given indices, with bound checks.
Panics
The function panics if any of the following conditions are violated:
row < self.nrows().col < self.ncols().
sourcepub unsafe fn write_unchecked(&mut self, row: usize, col: usize, value: E)
pub unsafe fn write_unchecked(&mut self, row: usize, col: usize, value: E)
Writes the value to the element at the given indices.
Safety
The behavior is undefined if any of the following conditions are violated:
row < self.nrows().col < self.ncols().
sourcepub fn write(&mut self, row: usize, col: usize, value: E)
pub fn write(&mut self, row: usize, col: usize, value: E)
Writes the value to the element at the given indices, with bound checks.
Panics
The function panics if any of the following conditions are violated:
row < self.nrows().col < self.ncols().
sourcepub fn copy_from_triangular_lower(&mut self, other: impl AsMatRef<E>)
pub fn copy_from_triangular_lower(&mut self, other: impl AsMatRef<E>)
Copies the values from the lower triangular part of other into the lower triangular
part of self. The diagonal part is included.
Panics
The function panics if any of the following conditions are violated:
self.nrows() == other.nrows().self.ncols() == other.ncols().self.nrows() == self.ncols().
sourcepub fn copy_from_strict_triangular_lower(&mut self, other: impl AsMatRef<E>)
pub fn copy_from_strict_triangular_lower(&mut self, other: impl AsMatRef<E>)
Copies the values from the lower triangular part of other into the lower triangular
part of self. The diagonal part is excluded.
Panics
The function panics if any of the following conditions are violated:
self.nrows() == other.nrows().self.ncols() == other.ncols().self.nrows() == self.ncols().
sourcepub fn copy_from_triangular_upper(&mut self, other: impl AsMatRef<E>)
pub fn copy_from_triangular_upper(&mut self, other: impl AsMatRef<E>)
Copies the values from the upper triangular part of other into the upper triangular
part of self. The diagonal part is included.
Panics
The function panics if any of the following conditions are violated:
self.nrows() == other.nrows().self.ncols() == other.ncols().self.nrows() == self.ncols().
sourcepub fn copy_from_strict_triangular_upper(&mut self, other: impl AsMatRef<E>)
pub fn copy_from_strict_triangular_upper(&mut self, other: impl AsMatRef<E>)
Copies the values from the upper triangular part of other into the upper triangular
part of self. The diagonal part is excluded.
Panics
The function panics if any of the following conditions are violated:
self.nrows() == other.nrows().self.ncols() == other.ncols().self.nrows() == self.ncols().
sourcepub fn copy_from(&mut self, other: impl AsMatRef<E>)
pub fn copy_from(&mut self, other: impl AsMatRef<E>)
Copies the values from other into self.
Panics
The function panics if any of the following conditions are violated:
self.nrows() == other.nrows().self.ncols() == other.ncols().
sourcepub fn fill_zero(&mut self)where
E: ComplexField,
pub fn fill_zero(&mut self)where
E: ComplexField,
Fills the elements of self with zeros.
sourcepub fn transpose_mut(self) -> Self
pub fn transpose_mut(self) -> Self
Returns a view over the transpose of self.
Example
use faer_core::mat;
let mut matrix = mat![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
let view = matrix.as_mut();
let transpose = view.transpose_mut();
let mut expected = mat![[1.0, 4.0], [2.0, 5.0], [3.0, 6.0]];
assert_eq!(expected.as_mut(), transpose);pub fn transpose(self) -> Self
MatMut::transpose_mutsourcepub fn conjugate_mut(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
pub fn conjugate_mut(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
Returns a view over the conjugate of self.
pub fn conjugate(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
MatMut::conjugate_mutsourcepub fn adjoint_mut(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
pub fn adjoint_mut(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
Returns a view over the conjugate transpose of self.
pub fn adjoint(self) -> MatMut<'a, E::Conj>where
E: Conjugate,
MatMut::adjoint_mutsourcepub fn canonicalize_mut(self) -> (MatMut<'a, E::Canonical>, Conj)where
E: Conjugate,
pub fn canonicalize_mut(self) -> (MatMut<'a, E::Canonical>, Conj)where
E: Conjugate,
Returns a view over the canonical representation of self, as well as a flag declaring
whether self is implicitly conjugated or not.
pub fn canonicalize(self) -> (MatMut<'a, E::Canonical>, Conj)where
E: Conjugate,
MatMut::canonicalize_mutsourcepub fn reverse_rows_mut(self) -> Self
pub fn reverse_rows_mut(self) -> Self
Returns a view over the self, with the rows in reversed order.
Example
use faer_core::mat;
let mut matrix = mat![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
let view = matrix.as_mut();
let reversed_rows = view.reverse_rows_mut();
let mut expected = mat![[4.0, 5.0, 6.0], [1.0, 2.0, 3.0]];
assert_eq!(expected.as_mut(), reversed_rows);pub fn reverse_rows(self) -> Self
MatMut::reverse_rows_mutsourcepub fn reverse_cols_mut(self) -> Self
pub fn reverse_cols_mut(self) -> Self
Returns a view over the self, with the columns in reversed order.
Example
use faer_core::mat;
let mut matrix = mat![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
let view = matrix.as_mut();
let reversed_cols = view.reverse_cols_mut();
let mut expected = mat![[3.0, 2.0, 1.0], [6.0, 5.0, 4.0]];
assert_eq!(expected.as_mut(), reversed_cols);pub fn reverse_cols(self) -> Self
MatMut::reverse_cols_mutsourcepub fn reverse_rows_and_cols_mut(self) -> Self
pub fn reverse_rows_and_cols_mut(self) -> Self
Returns a view over the self, with the rows and the columns in reversed order.
Example
use faer_core::mat;
let mut matrix = mat![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
let view = matrix.as_mut();
let reversed = view.reverse_rows_and_cols_mut();
let mut expected = mat![[6.0, 5.0, 4.0], [3.0, 2.0, 1.0]];
assert_eq!(expected.as_mut(), reversed);pub fn reverse_rows_and_cols(self) -> Self
MatMut::reverse_rows_and_cols_mutsourcepub fn submatrix_mut(
self,
row_start: usize,
col_start: usize,
nrows: usize,
ncols: usize
) -> Self
pub fn submatrix_mut( self, row_start: usize, col_start: usize, nrows: usize, ncols: usize ) -> Self
Returns a view over the submatrix starting at indices (row_start, col_start), and with
dimensions (nrows, ncols).
Panics
The function panics if any of the following conditions are violated:
row_start <= self.nrows().col_start <= self.ncols().nrows <= self.nrows() - row_start.ncols <= self.ncols() - col_start.
Example
use faer_core::mat;
let mut matrix = mat![
[1.0, 5.0, 9.0],
[2.0, 6.0, 10.0],
[3.0, 7.0, 11.0],
[4.0, 8.0, 12.0f64],
];
let view = matrix.as_mut();
let submatrix = view.submatrix_mut(2, 1, 2, 2);
let mut expected = mat![[7.0, 11.0], [8.0, 12.0f64]];
assert_eq!(expected.as_mut(), submatrix);pub fn submatrix( self, row_start: usize, col_start: usize, nrows: usize, ncols: usize ) -> Self
MatMut::submatrix_mutsourcepub fn subrows_mut(self, row_start: usize, nrows: usize) -> Self
pub fn subrows_mut(self, row_start: usize, nrows: usize) -> Self
Returns a view over the submatrix starting at row row_start, and with number of rows
nrows.
Panics
The function panics if any of the following conditions are violated:
row_start <= self.nrows().nrows <= self.nrows() - row_start.
Example
use faer_core::mat;
let mut matrix = mat![
[1.0, 5.0, 9.0],
[2.0, 6.0, 10.0],
[3.0, 7.0, 11.0],
[4.0, 8.0, 12.0f64],
];
let view = matrix.as_mut();
let subrows = view.subrows_mut(1, 2);
let mut expected = mat![[2.0, 6.0, 10.0], [3.0, 7.0, 11.0],];
assert_eq!(expected.as_mut(), subrows);pub fn subrows(self, row_start: usize, nrows: usize) -> Self
MatMut::subrows_mutsourcepub fn subcols_mut(self, col_start: usize, ncols: usize) -> Self
pub fn subcols_mut(self, col_start: usize, ncols: usize) -> Self
Returns a view over the submatrix starting at column col_start, and with number of
columns ncols.
Panics
The function panics if any of the following conditions are violated:
col_start <= self.ncols().ncols <= self.ncols() - col_start.
Example
use faer_core::mat;
let mut matrix = mat![
[1.0, 5.0, 9.0],
[2.0, 6.0, 10.0],
[3.0, 7.0, 11.0],
[4.0, 8.0, 12.0f64],
];
let view = matrix.as_mut();
let subcols = view.subcols_mut(2, 1);
let mut expected = mat![[9.0], [10.0], [11.0], [12.0f64]];
assert_eq!(expected.as_mut(), subcols);pub fn subcols(self, col_start: usize, ncols: usize) -> Self
MatMut::subcols_mutsourcepub fn row_mut(self, row_idx: usize) -> RowMut<'a, E>
pub fn row_mut(self, row_idx: usize) -> RowMut<'a, E>
Returns a view over the row at the given index.
Panics
The function panics if any of the following conditions are violated:
row_idx < self.nrows().
pub fn row(self, row_idx: usize) -> RowMut<'a, E>
MatMut::row_mutsourcepub fn col_mut(self, col_idx: usize) -> ColMut<'a, E>
pub fn col_mut(self, col_idx: usize) -> ColMut<'a, E>
Returns a view over the column at the given index.
Panics
The function panics if any of the following conditions are violated:
col_idx < self.ncols().
pub fn col(self, col_idx: usize) -> ColMut<'a, E>
MatMut::col_mutsourcepub fn column_vector_as_diagonal_mut(self) -> Matrix<DiagMut<'a, E>>
pub fn column_vector_as_diagonal_mut(self) -> Matrix<DiagMut<'a, E>>
Given a matrix with a single column, returns an object that interprets the column as a diagonal matrix, whoes diagonal elements are values in the column.
pub fn column_vector_as_diagonal(self) -> Matrix<DiagMut<'a, E>>
MatMut::column_vector_as_diagonal_mutpub fn diagonal_mut(self) -> Matrix<DiagMut<'a, E>>
pub fn diagonal(self) -> Matrix<DiagMut<'a, E>>
MatMut::diagonal_mutsourcepub fn to_owned(&self) -> Mat<E::Canonical>where
E: Conjugate,
pub fn to_owned(&self) -> Mat<E::Canonical>where
E: Conjugate,
Returns an owning Mat of the data
sourcepub fn has_nan(&self) -> boolwhere
E: ComplexField,
pub fn has_nan(&self) -> boolwhere
E: ComplexField,
Returns true if any of the elements is NaN, otherwise returns false.
sourcepub fn is_all_finite(&self) -> boolwhere
E: ComplexField,
pub fn is_all_finite(&self) -> boolwhere
E: ComplexField,
Returns true if all of the elements are finite, otherwise returns false.
sourcepub fn norm_max(&self) -> E::Realwhere
E: ComplexField,
pub fn norm_max(&self) -> E::Realwhere
E: ComplexField,
Returns the maximum norm of self.
sourcepub fn norm_l2(&self) -> E::Realwhere
E: ComplexField,
pub fn norm_l2(&self) -> E::Realwhere
E: ComplexField,
Returns the L2 norm of self.
sourcepub fn col_chunks_mut(
self,
chunk_size: usize
) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
pub fn col_chunks_mut( self, chunk_size: usize ) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
Returns an iterator that provides successive chunks of the columns of this matrix, with
each having at most chunk_size columns.
If the number of columns is a multiple of chunk_size, then all chunks have
chunk_size columns.
pub fn into_col_chunks( self, chunk_size: usize ) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
MatMut::col_chunks_mutsourcepub fn row_chunks_mut(
self,
chunk_size: usize
) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
pub fn row_chunks_mut( self, chunk_size: usize ) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
Returns an iterator that provides successive chunks of the rows of this matrix,
with each having at most chunk_size rows.
If the number of rows is a multiple of chunk_size, then all chunks have chunk_size
rows.
pub fn into_row_chunks( self, chunk_size: usize ) -> impl 'a + DoubleEndedIterator<Item = MatMut<'a, E>>
MatMut::row_chunks_mutsourcepub fn par_col_chunks_mut(
self,
chunk_size: usize
) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
pub fn par_col_chunks_mut( self, chunk_size: usize ) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
Returns a parallel iterator that provides successive chunks of the columns of this
matrix, with each having at most chunk_size columns.
If the number of columns is a multiple of chunk_size, then all chunks have
chunk_size columns.
Only available with the rayon feature.
pub fn into_par_col_chunks( self, chunk_size: usize ) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
MatMut::par_col_chunks_mutsourcepub fn par_row_chunks_mut(
self,
chunk_size: usize
) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
pub fn par_row_chunks_mut( self, chunk_size: usize ) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
Returns a parallel iterator that provides successive chunks of the rows of this matrix,
with each having at most chunk_size rows.
If the number of rows is a multiple of chunk_size, then all chunks have chunk_size
rows.
Only available with the rayon feature.
pub fn into_par_row_chunks( self, chunk_size: usize ) -> impl 'a + IndexedParallelIterator<Item = MatMut<'a, E>>
MatMut::par_row_chunks_mut