Struct all_is_cubes::math::Vol

pub struct Vol<C, O = ZMaj> { /* private fields */ }

Type for volume data stored in a slice, or for generating linear indexing.

• C is some slice container type, e.g. &[T] or Box<[T]>. It may also be () to describe a linearization without actually storing data.
• O specifies the choice of linearization. Currently, only one choice exists, ZMaj.

In addition to the data, each Vol stores the GridAab defining its size; the container’s length must be equal to the volume of that AAB. Whether that can be relied upon entirely depends on whether the specific container value produces the same length of slice every time it is Dereferenced without mutating it directly. For example, Vec<T> and Box<[T]> satisfy this criterion; the fact that [Vec] has length-mutating operations is irrelevant because no &mut Vec<T> is exposed.

A Vol whose volume exceeds usize::MAX cannot exist.

Implementations

impl<O> Vol<(), O>

pub fn with_elements<C, V>( self, elements: C, ) -> Result<Vol<C, O>, VolLengthError>

where C: Deref<Target = [V]>,

Attach some data to this dataless Vol.

Returns a VolLengthError if the number of elements does not match bounds.volume().

impl Vol<()>

pub fn subdivide(self) -> Option<(Vol<()>, Vol<()>)>

Divide self into two approximately equal-sized parts which, if they had elements, would each be contiguous in the linear ordering.

Returns None if self does not have at least two cubes.

Note that this is one of several subdivide() methods for different container types; it is also implemented for immutable and mutable references. These are intended to be useful in executing parallel algorithms on volume data.

impl<C, O, V> Vol<C, O>

where O: Default, C: Deref<Target = [V]>,

Constructors from linear containers.

pub fn from_elements( bounds: GridAab, elements: impl Into<C>, ) -> Result<Vol<C, O>, VolLengthError>

Constructs a Vol<C> containing the provided elements, which must be in the ordering specified by O.

Returns a VolLengthError if the number of elements does not match bounds.volume().

impl<C, V> Vol<C>

where C: Deref<Target = [V]> + FromIterator<V>,

Constructors from elements.

pub fn from_fn<F>(bounds: GridAab, f: F) -> Vol<C>

where F: FnMut(Cube) -> V,

Constructs a Vol<C> by using the provided function to compute a value for each point.

Panics if bounds has a volume exceeding usize::MAX. (But there will likely be a memory allocation failure well below that point.)

pub fn repeat(bounds: GridAab, value: V) -> Vol<C>

where V: Clone,

Constructs a Vol<C> by cloning the provided value for each point.

TODO: This feels like it should be called ‘filled’ or ‘cloned’, but if so, maybe FaceMap::repeat should also change?

pub fn from_element(value: V) -> Vol<C>

Constructs a Vol<C> with a single value, in bounds ORIGIN_CUBE.

If the single element should be at a different location, you can call .translate(offset), or use Vol::from_elements() instead.

impl<C, O> Vol<C, O>

pub fn bounds(&self) -> GridAab

Returns the GridAab specifying the bounds of this volume data.

pub fn volume(&self) -> usize

Returns the volume, also known as the number of elements.

pub fn into_elements(self) -> C

Extracts the linear contents, discarding the bounds and ordering.

pub fn without_elements(&self) -> Vol<(), O>

where O: Clone,

Returns a Vol with the same bounds and ordering but no data.

This is the inverse operation to Vol::with_elements().

pub fn translate(self, offset: impl Into<Vector3D<i32, Cube>>) -> Vol<C, O>

Translates the volume without affecting its contents.

Panics if this would cause numeric overflow.

TODO: example

impl<C> Vol<C>

pub fn iter_cubes(&self) -> GridIter

Iterate over all cubes that this contains, in the order of the linearization, without including the stored data (if there is any).

pub fn index(&self, cube: Cube) -> Option<usize>

Determines whether a unit cube lies within this volume and, if it does, returns the linearized slice index into it.

The linearized element order is defined by the O type.

use all_is_cubes::math::{Vol, GridAab};

let vol = GridAab::from_lower_size([0, 0, 0], [10, 10, 10]).to_vol().unwrap();

assert_eq!(vol.index([0, 0, 0].into()), Some(0));
assert_eq!(vol.index([1, 2, 3].into()), Some(123));
assert_eq!(vol.index([9, 9, 9].into()), Some(999));
assert_eq!(vol.index([0, 0, -1].into()), None);
assert_eq!(vol.index([0, 0, 10].into()), None);

TODO: more example, less unit-test

impl<C, O, V> Vol<C, O>

where C: Deref<Target = [V]>, O: Copy,

Linear data access.

pub fn as_ref(&self) -> Vol<&[V], O>

Return a Vol that borrows the contents of this one.

pub fn as_mut(&mut self) -> Vol<&mut [V], O>

where C: DerefMut,

Return a Vol that mutably borrows the contents of this one.

pub fn as_linear(&self) -> &[V]

Returns the linear contents viewed as a slice.

pub fn as_linear_mut(&mut self) -> &mut [V]

where C: DerefMut,

Returns the linear contents viewed as a mutable slice.

impl<'a, V> Vol<&'a [V]>

pub fn subdivide(self) -> Option<(Vol<&'a [V]>, Vol<&'a [V]>)>

Divide self into two approximately equal-sized parts, each of which refers to the appropriate sub-slice of elements.

Returns None if self does not have at least two cubes.

Note that this is one of several subdivide() methods for different container types; it is also implemented for mutable references and (). These are intended to be useful in executing parallel algorithms on volume data.

impl<'a, V> Vol<&'a mut [V]>

pub fn subdivide(self) -> Option<(Vol<&'a mut [V]>, Vol<&'a mut [V]>)>

Divide self into two approximately equal-sized parts. each of which refers to the appropriate sub-slice of elements.

Returns None if self does not have at least two cubes.

Note that this is one of several subdivide() methods for different container types; it is also implemented for immutable references and (). These are intended to be useful in executing parallel algorithms on volume data.

impl<C, V> Vol<C>

where C: Deref<Target = [V]>,

Element lookup operations by 3D coordinates.

pub fn get(&self, position: impl Into<Cube>) -> Option<&V>

Returns the element at position of this volume data, or None if position is out of bounds.

pub fn get_mut(&mut self, position: impl Into<Cube>) -> Option<&mut V>

where C: DerefMut,

Returns a mutable reference to the element at position of this volume data, or None if position is out of bounds.

pub fn iter<'s>(&'s self) -> impl Iterator<Item = (Cube, &'s V)> + Clone

where V: 's,

Iterates over all the cubes and values in this volume data, in the ordering specified by the O type parameter.

pub fn iter_mut<'s>(&'s mut self) -> impl Iterator<Item = (Cube, &'s mut V)>

where C: DerefMut, V: 's,

Iterates by mutable reference over all the cubes and values in this volume data, in the ordering specified by the O type parameter.

impl<V, O> Vol<Box<[V]>, O>

pub fn map<T, F>(self, f: F) -> Vol<Box<[T]>, O>

where F: FnMut(V) -> T,

Apply f to each element and collect the results into the same shape and ordering.

Trait Implementations

impl<'a, V, C> Arbitrary<'a> for Vol<C>

where V: Arbitrary<'a>, C: FromIterator<V> + Deref<Target = [V]>,

fn arbitrary(u: &mut Unstructured<'a>) -> Result<Vol<C>, Error>

Generate an arbitrary value of Self from the given unstructured data.

fn size_hint(depth: usize) -> (usize, Option<usize>)

Get a size hint for how many bytes out of an Unstructured this type needs to construct itself.

fn arbitrary_take_rest(u: Unstructured<'a>) -> Result<Self, Error>

Generate an arbitrary value of Self from the entirety of the given unstructured data.

impl<C, O> Clone for Vol<C, O>

where C: Clone, O: Clone,

fn clone(&self) -> Vol<C, O>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C, O> Debug for Vol<C, O>

where C: Debug, O: Debug,

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

Formats the value using the given formatter.

impl<C, O> Hash for Vol<C, O>

where C: Hash, O: Hash,

fn hash<__H>(&self, state: &mut __H)

where __H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<P, C, V> Index<P> for Vol<C>

where P: Into<Cube>, C: Deref<Target = [V]>,

fn index(&self, position: P) -> &<Vol<C> as Index<P>>::Output

Returns the element at position of this volume data, or panics if position is out of bounds.

Use Vol::get() for a non-panicing alternative.

type Output = V

The returned type after indexing.

impl<P, C, V> IndexMut<P> for Vol<C>

where P: Into<Cube>, C: DerefMut<Target = [V]>,

fn index_mut(&mut self, position: P) -> &mut <Vol<C> as Index<P>>::Output

Returns the element at position of this volume data, or panics if position is out of bounds.

impl<O> PartialEq<GridAab> for Vol<(), O>

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<O> PartialEq<Vol<(), O>> for GridAab

fn eq(&self, other: &Vol<(), O>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C, O> PartialEq for Vol<C, O>

where C: PartialEq, O: PartialEq,

fn eq(&self, other: &Vol<C, O>) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C, O> Copy for Vol<C, O>

where C: Copy, O: Copy,

impl<C, O> Eq for Vol<C, O>

where C: Eq, O: Eq,

impl SpaceBuilderBounds for Vol<()>

impl<C, O> StructuralPartialEq for Vol<C, O>