Struct easy_ml::tensors::indexing::TensorAccess

pub struct TensorAccess<T, S, const D: usize> { /* private fields */ }

Access to the data in a Tensor with a particular order of dimension indexing. The order affects the shape of the TensorAccess as well as the order of indexes you supply to read or write values to the tensor.

See the module level documentation for more information.

Implementations

impl<T, S, const D: usize> TensorAccess<T, S, D>where
    S: TensorRef<T, D>,

pub fn from(source: S, dimensions: [Dimension; D]) -> TensorAccess<T, S, D>

Creates a TensorAccess which can be indexed in the order of the supplied dimensions to read or write values from this tensor.

Panics

If the set of dimensions supplied do not match the set of dimensions in this tensor’s shape.

pub fn try_from(
    source: S,
    dimensions: [Dimension; D]
) -> Result<TensorAccess<T, S, D>, InvalidDimensionsError<D>>

Creates a TensorAccess which can be indexed in the order of the supplied dimensions to read or write values from this tensor.

Returns Err if the set of dimensions supplied do not match the set of dimensions in this tensor’s shape.

pub fn from_source_order(source: S) -> TensorAccess<T, S, D>

Creates a TensorAccess which is indexed in the same order as the dimensions in the view shape of the tensor it is created from.

Hence if you create a TensorAccess directly from a Tensor by from_source_order this uses the order the dimensions were laid out in memory with.

use easy_ml::tensors::Tensor;
use easy_ml::tensors::indexing::TensorAccess;
let tensor = Tensor::from([("x", 2), ("y", 2), ("z", 2)], vec![
    1, 2,
    3, 4,

    5, 6,
    7, 8
]);
let xyz = tensor.index_by(["x", "y", "z"]);
let also_xyz = TensorAccess::from_source_order(&tensor);
let also_xyz = tensor.index();

pub fn from_memory_order(source: S) -> Option<TensorAccess<T, S, D>>

Creates a TensorAccess which is indexed in the same order as the linear data layout dimensions in the tensor it is created from, or None if the source data layout is not linear.

Hence if you use from_memory_order on a source that was originally big endian like Tensor this uses the order for efficient iteration through each step in memory when iterating.

pub fn shape(&self) -> [(Dimension, usize); D]

The shape this TensorAccess has with the dimensions mapped to the order the TensorAccess was created with, not necessarily the same order as in the underlying tensor.

pub fn source(self) -> S

pub fn source_ref(&self) -> &S

impl<T, S, const D: usize> TensorAccess<T, S, D>where
    S: TensorRef<T, D>,

pub fn try_get_reference(&self, indexes: [usize; D]) -> Option<&T>

Using the dimension ordering of the TensorAccess, gets a reference to the value at the index if the index is in range. Otherwise returns None.

pub fn get_ref(&self, indexes: [usize; D]) -> &T

Using the dimension ordering of the TensorAccess, gets a reference to the value at the index if the index is in range, panicking if the index is out of range.

pub unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

Using the dimension ordering of the TensorAccess, gets a reference to the value at the index wihout any bounds checking.

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 TensorRef. Note that the order of the indexes needed here must match with TensorAccess::shape which may not neccessarily be the same as the view_shape of the TensorRef implementation this TensorAccess was created from).

pub fn iter_reference(
    &self
) -> TensorReferenceIterator<'_, T, TensorAccess<T, S, D>, D>

Returns an iterator over references to the data in this TensorAccess, in the order of the TensorAccess shape.

impl<T, S, const D: usize> TensorAccess<T, S, D>where
    S: TensorRef<T, D>,
    T: Clone,

pub fn get(&self, indexes: [usize; D]) -> T

Using the dimension ordering of the TensorAccess, gets a copy of the value at the index if the index is in range, panicking if the index is out of range.

For a non panicking API see try_get_reference

pub fn first(&self) -> T

Gets a copy of the first value in this tensor. For 0 dimensional tensors this is the only index [], for 1 dimensional tensors this is [0], for 2 dimensional tensors [0,0], etcetera.

pub fn map<U>(&self, mapping_function: impl Fn(T) -> U) -> Tensor<U, D>

Creates and returns a new tensor with all values from the original with the function applied to each.

Note: mapping methods are defined on Tensor and TensorView directly so you don’t need to create a TensorAccess unless you want to do the mapping with a different dimension order.

pub fn map_with_index<U>(
    &self,
    mapping_function: impl Fn([usize; D], T) -> U
) -> Tensor<U, D>

Creates and returns a new tensor with all values from the original and the index of each value mapped by a function. The indexes passed to the mapping function always increment the rightmost index, starting at all 0s, using the dimension order that the TensorAccess is indexed by, not neccessarily the index order the original source uses.

Note: mapping methods are defined on Tensor and TensorView directly so you don’t need to create a TensorAccess unless you want to do the mapping with a different dimension order.

pub fn iter(&self) -> TensorIterator<'_, T, TensorAccess<T, S, D>, D>

Returns an iterator over copies of the data in this TensorAccess, in the order of the TensorAccess shape.

impl<T, S, const D: usize> TensorAccess<T, S, D>where
    S: TensorMut<T, D>,

pub fn try_get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

Using the dimension ordering of the TensorAccess, gets a mutable reference to the value at the index if the index is in range. Otherwise returns None.

pub fn get_ref_mut(&mut self, indexes: [usize; D]) -> &mut T

Using the dimension ordering of the TensorAccess, gets a mutable reference to the value at the index if the index is in range, panicking if the index is out of range.

pub unsafe fn get_reference_unchecked_mut(
    &mut self,
    indexes: [usize; D]
) -> &mut T

Using the dimension ordering of the TensorAccess, gets a mutable reference to the value at the index wihout any bounds checking.

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 TensorRef. Note that the order of the indexes needed here must match with TensorAccess::shape which may not neccessarily be the same as the view_shape of the TensorRef implementation this TensorAccess was created from).

pub fn iter_reference_mut(
    &mut self
) -> TensorReferenceMutIterator<'_, T, TensorAccess<T, S, D>, D>

Returns an iterator over mutable references to the data in this TensorAccess, in the order of the TensorAccess shape.

impl<T, S, const D: usize> TensorAccess<T, S, D>where
    S: TensorMut<T, D>,
    T: Clone,

pub fn map_mut(&mut self, mapping_function: impl Fn(T) -> T)

Applies a function to all values in the tensor, modifying the tensor in place.

pub fn map_mut_with_index(
    &mut self,
    mapping_function: impl Fn([usize; D], T) -> T
)

Applies a function to all values and each value’s index in the tensor, modifying the tensor in place. The indexes passed to the mapping function always increment the rightmost index, starting at all 0s, using the dimension order that the TensorAccess is indexed by, not neccessarily the index order the original source uses.

Trait Implementations

impl<T: Clone, S: Clone, const D: usize> Clone for TensorAccess<T, S, D>

fn clone(&self) -> TensorAccess<T, S, D>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug, S: Debug, const D: usize> Debug for TensorAccess<T, S, D>

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

Formats the value using the given formatter.

impl<T, S, const D: usize> Display for TensorAccess<T, S, D>where
    T: Display,
    S: TensorRef<T, D>,

Any tensor access of a Displayable type implements Display

You can control the precision of the formatting using format arguments, i.e. format!("{:.3}", tensor)

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

Formats the value using the given formatter.

impl<T, S, const D: usize> TensorMut<T, D> for TensorAccess<T, S, D>where
    S: TensorMut<T, D>,

A TensorAccess implements TensorMut, with the dimension order and indexing matching that of the TensorAccess shape.

fn get_reference_mut(&mut self, indexes: [usize; D]) -> Option<&mut T>

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

unsafe fn get_reference_unchecked_mut(&mut self, indexes: [usize; D]) -> &mut T

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

impl<T, S, const D: usize> TensorRef<T, D> for TensorAccess<T, S, D>where
    S: TensorRef<T, D>,

A TensorAccess implements TensorRef, with the dimension order and indexing matching that of the TensorAccess shape.

fn get_reference(&self, indexes: [usize; D]) -> Option<&T>

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

fn view_shape(&self) -> [(Dimension, usize); D]

The shape this tensor has. See dimensions for an overview. The product of the lengths in the pairs define how many elements are in the tensor (or the portion of it that is visible).

unsafe fn get_reference_unchecked(&self, indexes: [usize; D]) -> &T

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

fn data_layout(&self) -> DataLayout<D>

The way the data in this tensor is laid out in memory. In particular, Linear has several requirements on what is returned that must be upheld by implementations of this trait.