Trait MatrixRef

pub unsafe trait MatrixRef<T>: NoInteriorMutability {
    // Required methods
    fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>;
    fn view_rows(&self) -> Row;
    fn view_columns(&self) -> Column;
    unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T;
    fn data_layout(&self) -> DataLayout;
}

A shared/immutable reference to a matrix (or a portion of it) of some type.

Indexing

Valid indexes into a MatrixRef range from 0 inclusive to view_rows exclusive for rows and from 0 inclusive to view_columns exclusive for columns. Even if a 4x4 matrix creates some 2x2 MatrixRef that can view only its center, the indexes used on the MatrixRef would be 0,0 to 1,1, not 1,1 to 2,2 as corresponding on the matrix. If the view_rows or view_columns are 0 then the MatrixRef has no valid indexes.

Safety

In order to support returning references without bounds checking in a useful way, the implementing type is required to uphold several invariants.

1 - Any valid index as described in Indexing will yield a safe reference when calling get_reference_unchecked and get_reference_unchecked_mut.

2 - The view_rows/view_columns that define which indexes are valid may not be changed by a shared reference to the MatrixRef implementation. ie, the matrix may not be resized while a mutable reference is held to it, except by that reference.

NB: Version 2 of Easy ML makes NoInteriorMutability a supertrait of MatrixRef. It is no longer possible to implement MatrixRef with interior mutability, which matches the 1.x TensorRef trait requirements. In a future major version, NoInteriorMutability will be removed and folded into the documentation on MatrixRef.

Essentially, interior mutability causes problems, since code looping through the range of valid indexes in a MatrixRef needs to be able to rely on that range of valid indexes not changing. This is trivially the case by default since a Matrix does not have any form of interior mutability, and therefore an iterator holding a shared reference to a Matrix prevents that matrix being resized. However, a type wrongly implementing MatrixRef could introduce interior mutability by putting the Matrix in an Arc<Mutex<>> which would allow another thread to resize a matrix while an iterator was looping through previously valid indexes on a different thread.

Note that it is okay to be able to resize any MatrixRef implementation if that always requires an exclusive reference to the MatrixRef/Matrix, since the exclusivity prevents the above scenario.

Required Methods

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_rows(&self) -> Row

The number of rows that this reference can view. This may be less than the actual number of rows of data stored in the matrix implementation, and could be 0.

fn view_columns(&self) -> Column

The number of columns that this reference can view. This may be less than the actual number of columns of data stored in the matrix implementation, and could be 0.

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see try_get_reference.

Safety

Calling this method with an out-of-bounds index is undefined behavior even if the resulting reference is not used. Valid indexes are defined as in MatrixRef.

fn data_layout(&self) -> DataLayout

A hint for the data layout this MatrixView uses to store its data.

See Matrix layout and iterator performance

Trait Implementations

impl<T> MatrixRef<T> for Box<dyn MatrixRef<T>>

A box of a dynamic MatrixRef also implements MatrixRef.

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

Gets a reference to the value at the index if the index is in range. Otherwise returns None.

fn view_rows(&self) -> Row

The number of rows that this reference can view. This may be less than the actual number of rows of data stored in the matrix implementation, and could be 0.

fn view_columns(&self) -> Column

The number of columns that this reference can view. This may be less than the actual number of columns of data stored in the matrix implementation, and could be 0.

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

Gets a reference to the value at the index without doing any bounds checking. For a safe alternative see try_get_reference.

fn data_layout(&self) -> DataLayout

A hint for the data layout this MatrixView uses to store its data.

impl<T> NoInteriorMutability for Box<dyn MatrixRef<T>>

A box of a dynamic MatrixRef also implements NoInteriorMutability, since NoInteriorMutability is supertrait of MatrixRef

Implementations on Foreign Types

impl<'source, T, S> MatrixRef<T> for &'source S

where S: MatrixRef<T>,

If some type implements MatrixRef, then a reference to it implements MatrixRef as well

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

fn view_rows(&self) -> Row

fn view_columns(&self) -> Column

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

fn data_layout(&self) -> DataLayout

impl<'source, T, S> MatrixRef<T> for &'source mut S

where S: MatrixRef<T>,

If some type implements MatrixRef, then an exclusive reference to it implements MatrixRef as well

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

fn view_rows(&self) -> Row

fn view_columns(&self) -> Column

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

fn data_layout(&self) -> DataLayout

impl<T> MatrixRef<T> for Box<dyn MatrixMut<T>>

A box of a dynamic MatrixMut also implements MatrixRef.

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

fn view_rows(&self) -> Row

fn view_columns(&self) -> Column

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

fn data_layout(&self) -> DataLayout

impl<T> MatrixRef<T> for Box<dyn MatrixRef<T>>

A box of a dynamic MatrixRef also implements MatrixRef.

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

fn view_rows(&self) -> Row

fn view_columns(&self) -> Column

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

fn data_layout(&self) -> DataLayout

impl<T, S> MatrixRef<T> for Box<S>

where S: MatrixRef<T>,

A box of a MatrixRef also implements MatrixRef.

fn try_get_reference(&self, row: Row, column: Column) -> Option<&T>

fn view_rows(&self) -> Row

fn view_columns(&self) -> Column

unsafe fn get_reference_unchecked(&self, row: Row, column: Column) -> &T

fn data_layout(&self) -> DataLayout

Implementors

impl<'a, T> MatrixRef<T> for MatrixPart<'a, T>

A MatrixPart implements MatrixRef.

impl<'a, T, S> MatrixRef<(T, usize)> for RecordMatrix<'a, T, S>

where T: Primitive, S: MatrixRef<(T, Index)>,

RecordMatrix implements MatrixRef when the source does, returning references to the tuples of T and Index.

impl<T> MatrixRef<T> for Matrix<T>

A Matrix implements MatrixRef.

impl<T, S> MatrixRef<T> for MatrixRefTensor<T, S>

where S: TensorRef<T, 2>,

impl<T, S> MatrixRef<T> for MatrixMask<T, S>

where S: MatrixRef<T>,

A MatrixMask of a MatrixRef type implements MatrixRef.

impl<T, S> MatrixRef<T> for MatrixRange<T, S>

where S: MatrixRef<T>,

A MatrixRange of a MatrixRef type implements MatrixRef.

impl<T, S> MatrixRef<T> for MatrixReverse<T, S>

where S: MatrixRef<T>,

A MatrixReverse implements MatrixRef, with the dimension names the MatrixReverse was created with iterating in reverse order compared to the dimension names in the original source.