Crate matrix_slice 

Implements references to blocks of a matrix.

Consider a reference to a slice (sometimes also just called slice). Typically, it is created by unsizing a reference to an array through type coercion, such as sing &[0, 1, 2] in a parameter to function that takes &[u32] which turns a reference &[u32; 3] to a slice &[u32]. The length of the slice, controlling the number of elements and thus the provenance of access that the reference allows, is stored in a tag alongside the pointer to its elements and initialized from the known length of the array. Since this tag is a runtime value we can manipulate it while upholding the invariants required by the type system.

This is analogous to that but for blocks of a matrix. A block is a rectangular region of a matrix where the matrix provides an underlying pitch (or stride) between rows and a total number of elements and the block the number of rows and columns that are spanned, i.e. are allowed to be accessed by (mutable) reference.

Treatment of empty blocks

A block may have zero rows or zero columns. In either case the block is empty and provides no access to any elements yet will still return an empty slice for some operations that would otherwise access multiple elements. The memory address of such a block is not necessarily at its expected location but it will be in-bounds of the underlying matrix data.

Consider the bottom right 2x2 block of a row-major 3x3 matrix.

+---+---+---+
| x | x | x |
+---+---+---+
| x | 4 | 5 |
+---+---+---+
| x | 7 | 8 |
+---+---+---+

This block has a pitch of 3 but only spans 2 columns. If we would naively calculate the address of its past-the-end element we would get an element below 7 which is out-of-bounds. Hence if we split this at row 2, into itself and an empty 0x2 block, the latter block’s data pointer would be created with undefined behavior. Instead, we sacrifice the ability to ‘locate’ such empty blocks and instead have them point at an arbitrary (empty) in-bounds slice within the matrix. (Currently, that is the start of the block from which it was created).

Structs

BlockMut

A reference to a block of a matrix with unique access to elements.

BlockRef

A reference to a block of a matrix with shared access to elements.

IterRows

Iterate over the rows of a block in a matrix.

IterRowsMut

Iterate over mutable rows of a block in a matrix.

Traits

MatrixIndex

Functions

from_array_rows

Create a block reference from a full matrix represented as an array of rows.

from_array_rows_mut

Create a mutable block reference from a full matrix represented as an array of rows.