Struct CircularArray 

pub struct CircularArray<const N: usize, A, T> { /* private fields */ }

A circular array of N dimensions for elements of type T.

Supports any fixed size contiguous element buffer implementing AsRef<[T]> and AsMut<T>.

General array data is accessible as associated methods while element access and mutation are delegated to CircularIndex and CircularMut.

Implementations

impl<const N: usize, A, T> CircularArray<N, A, T>

where A: AsRef<[T]>,

pub fn new(shape: [usize; N], array: A) -> CircularArray<N, A, T>

Create a new CircularArray from the given buffer.

Examples

let shape = [3, 3, 3];
let array = Vec::from_iter(0..shape.iter().product());

let circular_array = CircularArray::new(shape, array);

pub fn new_offset( shape: [usize; N], offset: [usize; N], array: A, ) -> CircularArray<N, A, T>

Create a new CircularArray from the given buffer and offset.

Examples

let shape = [3, 3, 3];
let array = Vec::from_iter(0..shape.iter().product());

// Offset by 1 on axis 0.
let circular_array = CircularArray::new_offset(shape, [1, 0, 0], array);

pub fn shape(&self) -> &[usize; N]

Get the array shape.

pub fn offset(&self) -> &[usize; N]

Get the array offset.

This is not always incremented sequentually. Where a mutating operation inserts elements equal to the product of the array shape, the offset will be set to [0; N].

pub fn offset_mut(&mut self) -> &mut [usize; N]

Get a mutable reference to the array offset.

Manually mutating the offset is not recommended unless clearing data. See also CircularArray::data_mut.

pub fn len(&self) -> usize

Get the number of elements in the array.

pub fn slice_len(&self, axis: usize) -> usize

Get the number of elements for a single slice of the buffer, for the given axis. Pushing n slices of elements onto an axis requires n * slice_len elements to be passed to the respective method.

Example

let mut array = CircularArray::new([4, 3, 2], vec![
     0,  1,  2,  3,
     4,  5,  6,  7,
     8,  9, 10, 11,

    12, 13, 14, 15,
    16, 17, 18, 19,
    20, 21, 22, 23,
]);

// A single slice of axis 0 is 6 elements.
assert_eq!(array.slice_len(0), 6);
assert_eq!(array.iter_index(0, 0).cloned().collect::<Vec<_>>(), [
     0,
     4,
     8,
    12,
    16,
    20
]);

// A single slice of axis 1 is 8 elements.
assert_eq!(array.slice_len(1), 8);
assert_eq!(array.iter_index(1, 0).cloned().collect::<Vec<_>>(), [
     0,  1,  2,  3,
    12, 13, 14, 15
]);

// A single slice of axis 2 is 12 elements.
assert_eq!(array.slice_len(2), 12);
assert_eq!(array.iter_index(2, 0).cloned().collect::<Vec<_>>(), [
     0,  1,  2,  3,
     4,  5,  6,  7,
     8,  9, 10, 11,
]);

pub fn take(self) -> A

Drop the CircularArray, returning the inner buffer. Note that data is returned without applying any normalizing operations.

pub fn data(&self) -> &A

Get a reference to the inner buffer A.

This may be useful for operations where element order is arbitrary. See also CircularIndex::iter_raw, CircularIndex::iter_index_raw and CircularIndex::iter_slice_raw.

pub fn data_mut(&mut self) -> &mut A

Get a mutable reference to the inner buffer A.

Manually mutating data is not recommended unless clearing data. See also CircularArray::offset_mut.

impl<const N: usize, T> CircularArray<N, Vec<T>, T>

pub fn from_iter(shape: [usize; N], iter: impl Iterator<Item = T>) -> Self

Create a new CircularArrayVec from an iterator.

Examples

let shape = [3, 3, 3];
let circular_array = CircularArrayVec::from_iter(shape, 0..shape.iter().product());

pub fn from_iter_offset( shape: [usize; N], offset: [usize; N], iter: impl Iterator<Item = T>, ) -> Self

Create a new CircularArrayVec from an iterator with the given offset.

Examples

let shape = [3, 3, 3];
// Offset by 1 on axis 0.
let circular_array = CircularArrayVec::from_iter_offset(shape, [1, 0, 0], 0..shape.iter().product());

impl<const N: usize, T> CircularArray<N, Box<[T]>, T>

pub fn from_iter(shape: [usize; N], iter: impl Iterator<Item = T>) -> Self

Create a new CircularArrayBox from an iterator.

Examples

let shape = [3, 3, 3];
let circular_array = CircularArrayBox::from_iter(shape, 0..shape.iter().product());

pub fn from_iter_offset( shape: [usize; N], iter: impl Iterator<Item = T>, offset: [usize; N], ) -> Self

Create a new CircularArrayBox from an iterator with the given offset.

Examples

let shape = [3, 3, 3];
// Offset by 1 on axis 0.
let circular_array = CircularArrayBox::from_iter_offset(shape, 0..shape.iter().product(), [1, 0, 0]);

Trait Implementations

impl<'a, const N: usize, A: AsRef<[T]>, T: 'a> CircularIndex<'a, N, T> for CircularArray<N, A, T>

fn iter(&'a self) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the inner array, aligned to the offset.

fn iter_raw(&'a self) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the inner array, ignoring the offset.

fn iter_index( &'a self, axis: usize, index: usize, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and index, aligned to the offset.

fn iter_index_contiguous( &'a self, axis: usize, index: usize, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and index, aligned to the offset in contiguous order.

fn iter_index_raw( &'a self, axis: usize, index: usize, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and index, ignoring the offset.

fn iter_range( &'a self, axis: usize, range: Range<usize>, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and range, aligned to the offset. This is equivalent to CircularIndex::iter_slice where all axis ranges are exhaustive with the exception of the specified axis.

fn iter_range_contiguous( &'a self, axis: usize, range: Range<usize>, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and range, aligned to the offset in contiguous order. This is equivalent to CircularIndex::iter_slice_contiguous where all axis ranges are exhaustive with the exception of the specified axis.

fn iter_range_raw( &'a self, axis: usize, range: Range<usize>, ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the specified axis and range, ignoring the offset. This is equivalent to CircularIndex::iter_slice_raw where all axis ranges are exhaustive except for the specified axis.

fn iter_slice( &'a self, slice: [Range<usize>; N], ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the given index slice, aligned to the offset.

fn iter_slice_contiguous( &'a self, slice: [Range<usize>; N], ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the given index slice, aligned to the offset in contiguous order.

fn iter_slice_raw( &'a self, slice: [Range<usize>; N], ) -> impl ExactSizeIterator<Item = &'a T>

Iterate over all elements of the given index slice, ignoring the offset.

fn get(&'a self, index: [usize; N]) -> &'a T

Get a reference to the element at the given index, aligned to the offset.

fn get_raw(&'a self, index: [usize; N]) -> &'a T

Get a reference to the element at the given index. This does not account for the offset. See CircularArray::offset.

impl<'a, const N: usize, A: AsRef<[T]> + AsMut<[T]>, T: Clone + 'a> CircularMut<'a, N, T> for CircularArray<N, A, T>

fn get_mut(&mut self, index: [usize; N]) -> &mut T

Get a mutable reference to the element at the given index, aligned to the offset.

fn get_mut_raw(&mut self, index: [usize; N]) -> &mut T

Get a mutable reference to the element at the given index. This does not account for the offset. See CircularArray::offset.

fn push_front(&'a mut self, axis: usize, el: &'a [T])

Push elements to the front of the given axis, aligned to the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_front_init(&'a mut self, axis: usize, n: usize, init: T)

Push n slices of elements to the front of the given axis, aligned to the offset. Elements are initialized with the provided init value.

fn push_front_iter<'b, I>(&mut self, axis: usize, el: I)

where I: IntoIterator<IntoIter: ExactSizeIterator, Item = &'b T>, T: 'b,

Push elements to the front of the given axis, aligned to the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_front_raw(&'a mut self, axis: usize, el: &'a [T])

Push elements to the front of the given axis, ignoring the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_front_raw_iter<'b, I>(&mut self, axis: usize, el: I)

where I: IntoIterator<IntoIter: ExactSizeIterator, Item = &'b T>, T: 'b,

Push elements to the front of the given axis, ignoring the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_back(&'a mut self, axis: usize, el: &'a [T])

Push elements to the back of the given axis, aligned to the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_back_init(&'a mut self, axis: usize, n: usize, init: T)

Push n slices of elements to the back of the given axis, aligned to the offset. Elements are initialized with the provided init value.

fn push_back_iter<'b, I>(&mut self, axis: usize, el: I)

where I: IntoIterator<IntoIter: ExactSizeIterator, Item = &'b T>, T: 'b,

Push elements to the back of the given axis, aligned to the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_back_raw(&'a mut self, axis: usize, el: &'a [T])

Push elements to the back of the given axis, ignoring the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn push_back_raw_iter<'b, I>(&mut self, axis: usize, el: I)

where I: IntoIterator<IntoIter: ExactSizeIterator, Item = &'b T>, T: 'b,

Push elements to the back of the given axis, ignoring the offset. Elements must be an exact multiple of the slice size for the given axis. See CircularArray::slice_len.

fn translate_front<'b, F>( &'a mut self, axis: usize, n: usize, origin: [usize; N], el_fn: F, )

where T: 'b, F: FnMut([Range<usize>; N]) -> &'b [T],

Translate the array by n on the given axis, inserting elements to the front of the array.

fn translate_back<'b, F>( &'a mut self, axis: usize, n: usize, origin: [usize; N], el_fn: F, )

where T: 'b, F: FnMut([Range<usize>; N]) -> &'b [T],

Translate the array by -n on the given axis, inserting elements to the back of the array.

fn translate_front_init(&'a mut self, axis: usize, n: usize, init: T)

where T: Clone,

Translate the array by n on the given axis, inserting elements to the front of the array. See CircularMut::push_front_init.

fn translate_back_init(&'a mut self, axis: usize, n: usize, init: T)

where T: Clone,

Translate the array by n on the given axis, inserting elements to the back of the array. See CircularMut::push_back_init.

impl<'a, const N: usize, A: AsRef<[T]>, T: 'a> Index<[usize; N]> for CircularArray<N, A, T>

type Output = T

The returned type after indexing.

fn index(&self, index: [usize; N]) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<'a, const N: usize, A: AsRef<[T]> + AsMut<[T]>, T: Clone + 'a> IndexMut<[usize; N]> for CircularArray<N, A, T>

fn index_mut(&mut self, index: [usize; N]) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.