Enum Mapping 

pub enum Mapping {
    Single,
    Linear(usize),
    Tiled(usize),
    Steps {
        base: usize,
        steps: Vec<Steps>,
    },
}

Positions of one argument over a result. Missing positions carry no value.

Variants

Single

One input item repeated.

Linear(usize)

Each input item repeats this many times.

Tiled(usize)

A cycle of this many input items.

Steps

Axis-separated offsets from the base.

Fields

base: usize

steps: Vec<Steps>

Implementations

impl Mapping

pub fn tabled(&self) -> bool

Whether an axis of this mapping reads through a table of positions, as a selection by data does, rather than by strides.

pub fn as_writes(&self) -> Option<Writes<'_>>

The writes at the places that a Mapping::Steps reads, in order, as From<Writes> makes one. None for any other mapping.

pub fn entries(&self, shape: &[usize]) -> Option<(usize, Vec<Steps>)>

This mapping as one entry per axis of shape, or None where offsets aren’t axis-separable.

pub fn through(&self, outer: &[Steps], shape: &[usize]) -> Option<Self>

Composes positional reads through the logical axes of shape.

pub fn split(&self, shape: &[usize]) -> Self

One entry per logical axis where the offsets separate by axis.

pub fn to_walk(&self, shape: &[usize]) -> (usize, Cow<'_, [Steps]>)

pub fn in_order(&self, len: usize, shape: &[usize]) -> bool

Whether a read through this mapping over a result of shape takes each of a source’s len items once, in order, from the first: a copy through it is the source unchanged, so a view of the source serves. Linear(1) answers at once, and any other mapping by its walk (Mapping::to_walk, Mapping::walk_in_order).

pub fn walk_in_order(base: usize, steps: &[Steps], len: usize) -> bool

Whether a walk from base through steps takes each of a source’s len items once, in order, from the first, as Mapping::in_order asks of a mapping’s walk. The walk needs exactly len positions, because a walk read past its last position starts again (Steps::reach).

pub fn tables(&self, shape: &[usize]) -> Vec<Steps>

Positional steps with the base as a leading singleton step.

pub fn footprint(&self) -> usize

The bytes that this mapping’s entries take: each entry, and a table’s listed offsets.

pub fn compose( &self, outer: &Self, shape: &[usize], frame: &[usize], ) -> Option<Self>

Composes a map from frame to shape with this map from shape to storage.

pub fn composed( &self, outer: &Self, shape: &[usize], frame: &[usize], table: bool, ) -> Option<Self>

Composes maps, listing offsets when structural composition fails and table is true. The listing walks each map once and looks every position of outer’s walk up in self‘s, where shape holds no more items than the result: a get divides on every axis for each item, about 400 instructions an item in negative windows’ composition with their padding.

pub fn affine(&self, shape: &[usize]) -> Option<(usize, Vec<isize>)>

First item offset and signed item strides, where the mapping is affine over shape: each axis reads one regular run with no fill, as Steps::affine decides.

pub fn block(&self, shape: &[usize]) -> Option<Block>

The contiguous block of storage that the mapping reads over shape, each item once, where the block’s axes come in another order or run backwards: as a transpose, a reversal or windows that don’t overlap read their source. None where the mapping skips, repeats or fills an item.

pub fn index(&self, i: usize) -> usize

The offset for position i. Panics where the mapping gives a fill.

pub fn run(&self, start: usize, n: usize) -> Option<(usize, isize)>

The first offset and stride of items start..start + n, where a Steps mapping reads one regular run.

pub fn get(&self, i: usize) -> Option<usize>

The offset for position i, or None where it reads a fill.

pub fn contract( left: &Layout, laxis: usize, right: &Layout, raxis: usize, ) -> Result<Self, Error>

For a contraction such as a matrix product: a one-axis mapping from each key on left’s axis laxis to its position on right’s axis raxis, as a table. Where the keys match, or either axis has none, positions pair in order.

pub fn new( input: &Layout, axes: &[usize], result: &Layout, count: usize, ) -> Self

How input lays out over result, which has count items. Axis a of input is axis axes[a] of result.

pub fn line_block(&self, size: usize) -> usize

The fewest items in a block of a read through this mapping, where its innermost axis skips items, as a transpose’s does: as many whole rows as a cache line holds items of size bytes, up to LINE_BLOCK items. The rows of such a block then share each fetch of a line. 0 where the innermost axis reads adjacent items or one item.

pub fn period(&self) -> Option<Period<'_>>

What this mapping’s positions read again, and over how many positions (Period): each item repeated (repeats), Tiled’s cycle, the cycle of a Steps mapping whose outer axes step by 0, as a broadcast along outer axes reads, or the cycle of one entry that wraps its whole source from the first item, as a reshape reads. None for one item, adjacent items, a mapping that fills, and other steps.

pub fn copies(&self, block: usize) -> bool

Whether expanded copies most blocks of block items read through this mapping, rather than reading them where they lie: steps whose runs of adjacent offsets (Steps::contiguous) are shorter than a block, as a transpose’s, a reversal’s, windows’ and a column slice’s are. Repeats and cycles don’t count: a run that stays inside one repeat or cycle reads in place, and the caller decides where runs end.

pub fn tiles_whole(&self, block: usize) -> bool

Whether a walk of blocks of block items through this mapping reads each item from its own cache line, where a walk of the whole copy reads them through the tiled transpose (Steps::transposing): after simplify, the last two axes form a transpose whose inner axis holds a block or more, so that each block walks one strided run. A copy made whole then costs much less than reads through it a block at a time.

pub fn regular(&self) -> Option<(usize, isize)>

The innermost stretch of positions that read at one regular stride, as its length and that stride: (r, 0) for Linear(r), each of whose stretches reads one item, and Steps::regular for steps.

pub fn repeats(&self) -> Option<usize>

The number of positions over which this mapping repeats each item: the length of its innermost regular stretch (regular) where that steps by 0, as Linear(r) does and a broadcast along inner axes does. None for one item, adjacent items, cycles and other steps.

pub fn runs(&self, positions: usize) -> Option<(usize, isize, Vec<usize>)>

The runs of this mapping’s innermost regular stretch (regular) over positions positions, where every run reads its items in place: the stretch’s length and stride, and the offset of each run’s first item, in the order of the runs. A Linear(r) mapping’s runs read its items in order. None where the mapping isn’t linear or steps, gives a fill, or reads its stretch through a padded or rotated axis.

pub fn fills(&self) -> bool

Whether some position reads a fill, as a padded read’s does.

pub fn spans( &self, range: Range<usize>, items: usize, f: &mut dyn FnMut(usize, usize, Option<(usize, isize)>) -> bool, )

Calls f(at, len, run) for consecutive spans of result positions range, in order, until it gives false: run holds the first position and stride of a span whose positions all lie below items, and is None for a span whose positions all miss. A Steps mapping gives the spans of each row of its innermost axis (row_spans), a repeat a span for each item, and a cycle a span for each pass.

Trait Implementations

impl Clone for Mapping

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Mapping

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for Mapping

impl<'a> From<&'a Mapping> for Walked<'a>

fn from(mapping: &'a Mapping) -> Self

Converts to this type from the input type.

impl From<Mapping> for Walked<'static>

fn from(mapping: Mapping) -> Self

Converts to this type from the input type.

impl From<Vec<Steps>> for Mapping

The mapping that walking tables reads, with the tables as they are.

fn from(tables: Vec<Steps>) -> Self

Converts to this type from the input type.

impl From<Writes<'_>> for Mapping

The mapping that reads the places that writes writes, in order: a list of offsets as one table, and a walk as its own steps.

fn from(writes: Writes<'_>) -> Self

Converts to this type from the input type.

impl PartialEq for Mapping

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Mapping