Struct CodedMatrix

Source

pub struct CodedMatrix<'a, E: Element, Bd: Bound, C: Codec<E, Bd>> { /* private fields */ }

Expand description

A borrowed matrix of codes, together with the codec that decodes them.

The codes are borrowed and the codec’s table is borrowed, so a CodedMatrix is a handful of pointers and three integers. Nothing here is owned, nothing is copied, and nothing is allocated (R7, C1).

Implementations§

Source §

impl<'a, E: Element, Bd: Bound, C: Codec<E, Bd>> CodedMatrix<'a, E, Bd, C>

Source

pub fn new( codec: C, rows: usize, cols: usize, codes: &'a [C::Code], ) -> Option<Self>

Borrow codes as an rows x cols coded matrix.

None only when the codes do not describe the declared shape, which means no such matrix exists. There is nothing else to validate: the codec’s table is already Alphabet<E, Bd>, so its image is in the alphabet by construction (§6.3).

CK-06: the codec’s own decoded lengths must sum to the declared row width, on every row. It is the codec that says how long a code is, so a variable-length tier needs no special case here and no separate matrix type — which is what makes run coding a tier rather than a second algorithm (S5b).

Source

pub const fn rows(&self) -> usize

Rows.

Source

pub const fn cols(&self) -> usize

Decoded elements per row.

Source

pub const fn codec(&self) -> &C

The codec.

Source

pub const fn codes_per_row(&self) -> usize

Codes per row, for a fixed-width tier.

A variable-length tier has no such constant; use CodedMatrix::row_code_range, which walks the codec’s own lengths.

Source

pub fn row_code_range(&self, r: usize) -> Range<usize> ⓘ

The half-open range of codes belonging to row r.

Arithmetic for a fixed-width tier, which is every tier but a run codec. That matters more than it looks: for a run codec this walks rows 0..r, so a driver reading one element at a time runs in O(k^2 n) instead of O(m k n). CodedMatrix::column_walk is what a driver uses instead — it carries the cursor from row to row, so a column is one pass over the codes whatever the tier.

Source

pub const fn codec_ref(&self) -> &C

The codec, for a walker that has to ask it lengths.

Source

pub const fn codes(&self) -> &'a [C::Code]

The raw code slice.

Source

pub fn decode_row_into(&self, r: usize, out: &mut [Alphabet<E, Bd>]) -> usize

Decode row r. out.len() >= cols. The caller owns the buffer.

Returns how many elements were written, which CodedMatrix::new established is exactly cols (CK-06).

Source

pub fn decode_range_into( &self, r: usize, cols: Range<usize>, out: &mut [Alphabet<E, Bd>], )

Streaming decode, for a caller whose buffer is smaller than one row.

This is what makes the library usable on a microcontroller whose RAM cannot hold a decoded row, and it is what makes the zero-scratch traversal possible (S13).

Source

pub fn column_walk<'m>(&'m self, c: usize) -> ColumnWalk<'m, 'a, E, Bd, C> ⓘ

Column c, walked down every row, in one pass over the codes.

CodedMatrix::at is O(1) for a fixed-width tier and O(row) for a variable-length one — plus the CodedMatrix::row_code_range walk over rows 0..r. A driver that loops for r in 0..rows { at(r, c) } therefore pays O(rows^2) on a run codec, which is exactly the hazard the note on row_code_range names, and exactly what the zero-offer coded traversal was doing: O(m n k^2) where the identity is O(m n k).

This carries the cursor from one row to the next, so a whole column costs one pass over the codes whatever the tier. It allocates nothing: the state is two indices (R7).

Source

pub fn at(&self, r: usize, c: usize) -> Alphabet<E, Bd>

The element at (r, c) of the decoded matrix.

O(1) for a fixed-width tier. For a variable-length one it walks the row, because the run boundaries are the data; a caller reading a whole row from such a tier should use CodedMatrix::decode_row_into, which walks it once instead of once per element.