Trait matrixable::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.

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>