Trait MatrixMutExt

pub trait MatrixMutExt: MatrixExt {
    // Required method
    fn get_mut(
        &mut self,
        row: usize,
        column: usize,
    ) -> Option<&mut Self::Element>;

    // Provided methods
    unsafe fn get_unchecked_mut(
        &mut self,
        row: usize,
        column: usize,
    ) -> &mut Self::Element { ... }
    fn get_nth_mut(&mut self, n: usize) -> Option<&mut Self::Element> { ... }
    unsafe fn get_nth_unchecked_mut(&mut self, n: usize) -> &mut Self::Element { ... }
    fn first_mut(&mut self) -> Option<&mut Self::Element> { ... }
    fn last_mut(&mut self) -> Option<&mut Self::Element> { ... }
    fn set(
        &mut self,
        subscripts: (usize, usize),
        val: Self::Element,
    ) -> Result<(), &'static str> { ... }
    fn set_nth(
        &mut self,
        n: usize,
        val: Self::Element,
    ) -> Result<(), &'static str> { ... }
    fn swap(&mut self, a: (usize, usize), b: (usize, usize)) { ... }
    fn swapn(&mut self, a: usize, b: usize) { ... }
    fn swap_cols(&mut self, col1: usize, col2: usize) { ... }
    fn swap_rows(&mut self, row1: usize, row2: usize) { ... }
    fn iter_mut(&mut self) -> IterMut<'_, Self> 
       where Self: Sized { ... }
    fn row_mut(&mut self, i: usize) -> Option<RowMut<'_, Self>>
       where Self: Sized { ... }
    unsafe fn row_unchecked_mut(&mut self, i: usize) -> RowMut<'_, Self> 
       where Self: Sized { ... }
    fn col_mut(&mut self, j: usize) -> Option<ColumnMut<'_, Self>>
       where Self: Sized { ... }
    unsafe fn col_unchecked_mut(&mut self, j: usize) -> ColumnMut<'_, Self> 
       where Self: Sized { ... }
    fn diag_mut(&mut self, n: usize) -> Option<DiagMut<'_, Self>>
       where Self: Sized { ... }
    unsafe fn diag_unchecked_mut(&mut self, n: usize) -> DiagMut<'_, Self> 
       where Self: Sized { ... }
    fn main_diag_mut(&mut self) -> DiagMut<'_, Self> 
       where Self: Sized { ... }
    fn enumerate_mut(&mut self) -> Enumerator<IterMut<'_, Self>> 
       where Self: Sized { ... }
    fn rows_mut(&mut self) -> RowsMut<'_, Self> 
       where Self: Sized { ... }
    fn cols_mut(&mut self) -> ColumnsMut<'_, Self> 
       where Self: Sized { ... }
    fn diags_mut(&mut self) -> DiagsMut<'_, Self> 
       where Self: Sized { ... }
    fn access_mut<S: AccessStrategy<Self>>(
        &mut self,
        strategy: S,
    ) -> AccessMut<'_, Self, S>
       where Self: Sized { ... }
    fn in_place<S: InPlace<Self>>(&mut self, strategy: S)
       where Self: Sized { ... }
}

This trait adds mutable access and some additional methods to MatrixExt implementors.

Required Methods

fn get_mut(&mut self, row: usize, column: usize) -> Option<&mut Self::Element>

Returns a mutable reference to a value inside the matrix, at the intersection of the i-th row and the j-th column.

Provided Methods

unsafe fn get_unchecked_mut( &mut self, row: usize, column: usize, ) -> &mut Self::Element

Returns a mutable reference to an element, without doing bounds checking.

For a safe alternative see get_mut.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

You can think of this like .get_mut(row_index, column_index).unwrap_unchecked().

Example

use matrixable::MatrixMutExt;

let x = &mut [[1, 2, 4]];

unsafe {
    let elem = x.get_unchecked_mut(0, 1);
       *elem = 13;
}

assert_eq!(x, &[[1, 13, 4]]);

fn get_nth_mut(&mut self, n: usize) -> Option<&mut Self::Element>

Example

use matrixable::MatrixMutExt;

let mut v = [[0, 1, 3, 3, 4, 5]];

assert_eq!(3, v[0][2]);

let n = v.get_nth_mut(2).unwrap();
*n = 2;

assert_eq!(2, v[0][2]);

unsafe fn get_nth_unchecked_mut(&mut self, n: usize) -> &mut Self::Element

Returns mutable a reference to an element given its linear order, without doing bound checking.

For a safe alternative see get_nth_mut.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used.

You can think of this like .get_nth_mut(index).unwrap_unchecked().

Example

use matrixable::MatrixMutExt;

let x = &mut [[1, 2, 4]];

unsafe {
    let elem = x.get_nth_unchecked_mut(1);
       *elem = 13;
}

assert_eq!(x, &[[1, 13, 4]]);

fn first_mut(&mut self) -> Option<&mut Self::Element>

Returns a mutable pointer to the first element of the matrix, or None if it is empty.

fn last_mut(&mut self) -> Option<&mut Self::Element>

Returns a mutable pointer to the last element of the matrix, or None if it is empty.

fn set( &mut self, subscripts: (usize, usize), val: Self::Element, ) -> Result<(), &'static str>

Changes the value of an element at the intersection of the i-th row and the j-th column of the matrix.

Error

An error is returned if any of those indexes are out of bounds.

Example

use matrixable::{MatrixExt, MatrixMutExt}; 
 
let mut m = [[1, 2, 3]];

assert_eq!(Ok(()), m.set((0, 2), 100));
assert_eq!(Some(&100), m.get(0, 2));

assert_eq!(Err("Cannot access element from indexes."), m.set((1, 0), 11));

fn set_nth(&mut self, n: usize, val: Self::Element) -> Result<(), &'static str>

Changes the value of the n-th element of the matrix.

Error

An error is returned if n is out of bound.

Example

use matrixable::{MatrixExt, MatrixMutExt}; 
 
let mut m = [[1, 2, 3]];

assert_eq!(Ok(()), m.set_nth(2, 100));
assert_eq!(Some(&100), m.get(0, 2));

assert_eq!(Err("Cannot access element from index."), m.set_nth(3, 11));

fn swap(&mut self, a: (usize, usize), b: (usize, usize))

Swaps two elements in the matrix identified by their subscripts.

If a equals to b, it’s guaranteed that elements won’t change value.

Arguments

• a - The index of the first element
• b - The index of the second element

Panics

Panics if a or b are out of bounds.

Example

use matrixable::MatrixMutExt;

let mut m = [
    [(0,0), (0,1), (0,2)],
    [(1,0), (1,1), (1,2)],
    [(2,0), (2,1), (2,2)]
];
 
m.swap((0,1), (2,2));

let expected = [
   [(0,0), (2,2), (0,2)],
   [(1,0), (1,1), (1,2)],
   [(2,0), (2,1), (0,1)]
];

assert_eq!(expected, m);

fn swapn(&mut self, a: usize, b: usize)

Swaps two elements in the matrix identified by their linear position following the Row Major Order.

If a equals to b, it’s guaranteed that elements won’t change value.

Arguments

• a - The index of the first element
• b - The index of the second element

Panics

Panics if a or b are out of bounds.

Example

use matrixable::MatrixMutExt;

let mut m = [
    [(0,0), (0,1), (0,2)],
    [(1,0), (1,1), (1,2)],
    [(2,0), (2,1), (2,2)]
];

m.swapn(2, 7);
 
let expected = [
        [(0,0), (0,1), (2,1)],
        [(1,0), (1,1), (1,2)],
        [(2,0), (0,2), (2,2)]
];

assert_eq!(expected, m);

fn swap_cols(&mut self, col1: usize, col2: usize)

Swaps two columns.

Panics

Panics if a column index is out of bound.

fn swap_rows(&mut self, row1: usize, row2: usize)

Swaps two rows.

Panics

Panics if a row index is out of bound.

fn iter_mut(&mut self) -> IterMut<'_, Self>

where Self: Sized,

Returns an iterator that allows modifying each element.

Iteration follows the Row Major Order.

Example

use matrixable::MatrixMutExt;
let x = &mut [[1, 2, 4], [2, 5, 6]];
 
let third = x.iter_mut().nth(2).unwrap();
*third = 3;

let fourth = x.iter_mut().nth(3).unwrap();
*fourth = 4;

assert_eq!(x, &mut [[1, 2, 3], [4, 5, 6]]);

fn row_mut(&mut self, i: usize) -> Option<RowMut<'_, Self>>

where Self: Sized,

Returns an iterator that allows modifying each element of the i-th row.

None is returned if i >= number of rows.

Example

use matrixable::MatrixMutExt;

let x = &mut [[1, 2, 4], [2, 5, 6]];
 
for elem in x.row_mut(1).unwrap() {
    *elem = 0;
}
 
assert_eq!(x, &mut [[1, 2, 4], [0, 0, 0]]);

unsafe fn row_unchecked_mut(&mut self, i: usize) -> RowMut<'_, Self>

where Self: Sized,

Returns an iterator over the mutable elements of the i-th row, without doing bound checking.

fn col_mut(&mut self, j: usize) -> Option<ColumnMut<'_, Self>>

where Self: Sized,

Returns an iterator over that allows modifying each element of the j-th column.

None is returned if j >= number of columns.

Example

use matrixable::MatrixMutExt;

let x = &mut [[1, 2, 4], [2, 5, 6]];
 
for elem in x.col_mut(1).unwrap() {
    *elem += 3;
}
 
assert_eq!(x, &mut [[1, 5, 4], [2, 8, 6]]);

unsafe fn col_unchecked_mut(&mut self, j: usize) -> ColumnMut<'_, Self>

where Self: Sized,

Returns an iterator over the mutable elements of the j-th column, without doing bound checking.

fn diag_mut(&mut self, n: usize) -> Option<DiagMut<'_, Self>>

where Self: Sized,

Returns an iterator over that allows modifying each element of the n-th diagonal.

None is returned if n >= number of diagonals.

Example

use matrixable::MatrixMutExt;

let m = &mut [
    [0, 0, 0],
    [0, 0, 0],
    [0, 0, 0]
];
     
for elem in m.diag_mut(2).unwrap() {    
    *elem = 1;
}
 
assert_eq!(&mut [
    [1, 0, 0],
    [0, 1, 0],
    [0, 0, 1],
], m);

unsafe fn diag_unchecked_mut(&mut self, n: usize) -> DiagMut<'_, Self>

where Self: Sized,

Returns an iterator over the mutable elements of the n-th diagonal, without doing bound checking.

fn main_diag_mut(&mut self) -> DiagMut<'_, Self>

where Self: Sized,

Returns the main diagonal (mutable).

Example

use matrixable::MatrixMutExt;

let m = &mut [
    [0, 0],
    [0, 0],
    [0, 0]
];
     
// for elem in m.diag_mut(2).unwrap() {    
for elem in m.main_diag_mut() {    
    *elem = 1;
}
 
assert_eq!(&mut [
    [1, 0],
    [0, 1],
    [0, 0],
], m);

fn enumerate_mut(&mut self) -> Enumerator<IterMut<'_, Self>>

where Self: Sized,

[.enumerate()] with mutable access to each element.

Example

use matrixable::MatrixMutExt;

let mut  m = [[1, 2], [3, 4], [5, 6]];
let mut en = m.enumerate_mut();
 
assert_eq!(Some((0, 0, &mut 1)), en.next());
assert_eq!(Some((0, 1, &mut 2)), en.next());
assert_eq!(Some((1, 0, &mut 3)), en.next());
assert_eq!(Some((1, 1, &mut 4)), en.next());
assert_eq!(Some((2, 0, &mut 5)), en.next());
assert_eq!(Some((2, 1, &mut 6)), en.next());
assert_eq!(None, en.next());

fn rows_mut(&mut self) -> RowsMut<'_, Self>

where Self: Sized,

Returns an iterator over the rows with mutable access to elements.

Example

use matrixable::MatrixMutExt;

let mut m = [[1, 2], [3, 4], [5, 6]];
 
let mut rows = m.rows_mut();
 
assert_eq!(vec![&mut 1, &mut 2], rows.next().unwrap().collect::<Vec<_>>());
assert_eq!(vec![&mut 3, &mut 4], rows.next().unwrap().collect::<Vec<_>>());
assert_eq!(vec![&mut 5, &mut 6], rows.next().unwrap().collect::<Vec<_>>());
assert!(rows.next().is_none());

fn cols_mut(&mut self) -> ColumnsMut<'_, Self>

where Self: Sized,

Returns an iterator over the columns of the matrix with mutable access to elements.

Example

use matrixable::MatrixMutExt;

let mut m = [[1, 2], [3, 4], [5, 6]];
 
let mut cols = m.cols_mut();
 
assert_eq!(vec![&mut 1, &mut 3, &mut 5], cols.next().unwrap().collect::<Vec<_>>());
assert_eq!(vec![&mut 2, &mut 4, &mut 6], cols.next().unwrap().collect::<Vec<_>>());
assert!(cols.next().is_none());

fn diags_mut(&mut self) -> DiagsMut<'_, Self>

where Self: Sized,

Returns an iterator over the diagonals with mutable access to elements.

Example

use matrixable::MatrixMutExt;
 
let mut m = [[0, 0, 0]; 3];

let mut i = 0;
for diag in m.diags_mut() {
    i += 1;
    for elem in diag {
        *elem = i;
    }
}

assert_eq!([
    [3, 4, 5],
    [2, 3, 4],
    [1, 2, 3]
], m);

fn access_mut<S: AccessStrategy<Self>>( &mut self, strategy: S, ) -> AccessMut<'_, Self, S>

where Self: Sized,

Creates a matrix to mutably access elements of this matrix following an AccessStrategy.

Example

use matrixable::MatrixMutExt;
use matrixable::strategies::{AccessStrategy, Reverse};

let mut m = [[1, 2], [3, 4]];
 
m.access_mut(Reverse).set((0,0), 11).unwrap();

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

By repeating this method you can obtain a more complex access.

use matrixable::{MatrixMutExt};
use matrixable::strategies::{Reverse, ShiftBack};
  
let mut m = [[1, 2, 3, 4], [5, 6, 7, 8]];

m.access_mut(Reverse) // [[8, 7, 6, 5], [4, 3, 2, 1]]
 .access_mut(ShiftBack(5))  // [[3, 2, 1, 8], [7, 6, 5, 4]]
 .col_mut(0) // [3, 7]
 .unwrap()
 .for_each(|x| *x = 11);

assert_eq!([[1, 2, 11, 4], [5, 6, 11, 8]], m);

However, prefer using AccessStrategySet method if you have a considerable number of AccessStrategys to chain.

fn in_place<S: InPlace<Self>>(&mut self, strategy: S)

where Self: Sized,

Modifies the matrix InPlace according to a certain strategy.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<T, const N: usize, const M: usize> MatrixMutExt for [[T; N]; M]

fn get_mut(&mut self, i: usize, j: usize) -> Option<&mut Self::Element>

Implementors

impl<'a, M: MatrixMutExt, S: AccessStrategy<M>> MatrixMutExt for AccessMut<'a, M, S>