Trait Matrix 

pub unsafe trait Matrix {
    type Element;

    // Required methods
    fn as_nonnull(&self) -> NonNull<Self::Element>;
    fn layout(&self) -> Layout<Self::Element>;

    // Provided methods
    fn nrows(&self) -> usize { ... }
    fn ncols(&self) -> usize { ... }
    unsafe fn row_unchecked(&self, row: usize) -> &[Self::Element] { ... }
    fn as_ptr(&self) -> *const Self::Element { ... }
    fn as_slice(&self) -> &[Self::Element] { ... }
    fn row(&self, row: usize) -> &[Self::Element] { ... }
    fn get_row(&self, row: usize) -> Option<&[Self::Element]> { ... }
    fn rows(&self) -> Rows<'_, Self::Element>  { ... }
    unsafe fn element_unchecked(&self, row: usize, col: usize) -> &Self::Element { ... }
    fn get_element(&self, row: usize, col: usize) -> Option<&Self::Element> { ... }
    fn element(&self, row: usize, col: usize) -> &Self::Element { ... }
    fn as_view(&self) -> Ref<'_, Self::Element> { ... }
    fn subview(&self, rows: Range<usize>) -> Option<Ref<'_, Self::Element>> { ... }
    fn window_iter(&self, batchsize: NonZeroUsize) -> Windows<'_, Self::Element>  { ... }
    fn to_rowmajor_owned(&self) -> Owned<Self::Element>
       where Self::Element: Clone { ... }
    fn try_map<F, R>(&self, f: F) -> Result<Owned<R>, LayoutError>
       where F: FnMut(&Self::Element) -> R { ... }
    fn map<F, R>(&self, f: F) -> Owned<R>
       where F: FnMut(&Self::Element) -> R { ... }
    fn transpose(&self) -> Owned<Self::Element>
       where Self::Element: Clone { ... }
    fn par_rows(&self) -> impl IndexedParallelIterator<Item = &[Self::Element]>
       where Self::Element: Sync { ... }
    fn par_window_iter(
        &self,
        batchsize: usize,
    ) -> impl IndexedParallelIterator<Item = Ref<'_, Self::Element>>
       where Self::Element: Sync { ... }
}

Tools for treating contiguous regions of memory as a dense, row-major matrix.

See also: MatrixMut, Owned, Ref, Mut.

Safety

For any shared reference matrix: &Self, the following must hold for the entire lifetime of that reference:

• Every call to matrix.as_nonnull() returns the same pointer.

• Every call to matrix.layout() returns the same layout.

• The pointer and layout describe the same valid initialized span throughout that lifetime. Given:

  let data = matrix.as_nonnull();
  let layout = matrix.layout();

  constructing the following slice is valid:

  unsafe { std::slice::from_raw_parts(data.as_ptr().cast_const(), layout.num_elements()) };

  In particular:

  • data must be properly aligned, including when layout.num_elements() == 0.

  • If both layout.num_elements() and size_of::<Self::Element>() are nonzero, the described span must lie within a single allocation.

  • The span must contain layout.num_elements() consecutive, properly initialized values of type Self::Element.

  • The referenced memory must not be mutated for the lifetime of matrix, except through an UnsafeCell.

Required Associated Types

type Element

The type of the element stored in the matrix.

Required Methods

fn as_nonnull(&self) -> NonNull<Self::Element>

Return the base pointer for the matrix.

fn layout(&self) -> Layout<Self::Element>

Return the Layout for the matrix.

Provided Methods

fn nrows(&self) -> usize

Return the number of rows in the matrix.

fn ncols(&self) -> usize

Return the number of columns in the matrix.

unsafe fn row_unchecked(&self, row: usize) -> &[Self::Element]

Returns the requested row without bounds checking.

Safety

The following conditions must hold to avoid undefined behavior:

• row < self.nrows().

fn as_ptr(&self) -> *const Self::Element

Return a pointer to the base of the matrix.

fn as_slice(&self) -> &[Self::Element]

Return the underlying data as a slice.

fn row(&self, row: usize) -> &[Self::Element]

Return row row as a slice.

Panic

Panics if row >= self.nrows().

fn get_row(&self, row: usize) -> Option<&[Self::Element]>

Return row row if row < self.nrows(). Otherwise, return None.

fn rows(&self) -> Rows<'_, Self::Element>

Return a iterator over all rows in the matrix.

Rows are yielded sequentially beginning with row 0.

unsafe fn element_unchecked(&self, row: usize, col: usize) -> &Self::Element

Returns a reference to an element without bounds checking.

Safety

The following conditions must hold to avoid undefined behavior:

• row < self.nrows().
• col < self.ncols().

fn get_element(&self, row: usize, col: usize) -> Option<&Self::Element>

Return the value at the specified row and col.

If either index is out-of-bounds, return None.

fn element(&self, row: usize, col: usize) -> &Self::Element

Return the value at the specified row and col.

Panics

Panics if either row or col is out-of-bounds.

fn as_view(&self) -> Ref<'_, Self::Element>

Return a view over the matrix.

fn subview(&self, rows: Range<usize>) -> Option<Ref<'_, Self::Element>>

Return a view over the rows in rows, or None when the range is invalid.

fn window_iter(&self, batchsize: NonZeroUsize) -> Windows<'_, Self::Element>

Return an iterator that divides the matrix into sub-matrices with (up to) batchsize rows with self.ncols() columns.

It is possible for yielded sub-matrices to have fewer than batchsize rows if the number of rows in the parent matrix is not evenly divisible by batchsize.

fn to_rowmajor_owned(&self) -> Owned<Self::Element>

where Self::Element: Clone,

Return an Owned with the same shape as self and cloned contents.

fn try_map<F, R>(&self, f: F) -> Result<Owned<R>, LayoutError>

where F: FnMut(&Self::Element) -> R,

Create a new Matrix by applying the closure f to each element.

The returned matrix has the same shape as self.

fn map<F, R>(&self, f: F) -> Owned<R>

where F: FnMut(&Self::Element) -> R,

Create a new Matrix by applying the closure f to each element.

The returned matrix has the same shape as self.

Panics

Panics if allocating space for Owned would overflow isize::MAX.

fn transpose(&self) -> Owned<Self::Element>

where Self::Element: Clone,

Transpose the elements in self.

fn par_rows(&self) -> impl IndexedParallelIterator<Item = &[Self::Element]>

where Self::Element: Sync,

Return a parallel iterator over the rows of the matrix.

fn par_window_iter( &self, batchsize: usize, ) -> impl IndexedParallelIterator<Item = Ref<'_, Self::Element>>

where Self::Element: Sync,

Return a parallel iterator that divides the matrix into sub-matrices with (up to) batchsize rows with self.ncols() columns.

This allows workers in parallel algorithms to work on dense subsets of the whole matrix for better locality.

It is possible for yielded sub-matrices to have fewer than batchsize rows if the number of rows in the parent matrix is not evenly divisible by batchsize.

Panics

Panics if batchsize = 0.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl<T> Matrix for Mut<'_, T>

type Element = T

impl<T> Matrix for Owned<T>

type Element = T

impl<T> Matrix for Ref<'_, T>

type Element = T