Struct FunVec

pub struct FunVec<D, T, F, C = UnboundedCard<D>>
where
    D: Dim,
    F: Fn(D::Idx) -> T,
    C: Card<D>,
{ /* private fields */ }

A functional vector of dimension D and cardinality C having T scalar elements.

So much generics, but the important bit is:

• any FunVec<D, T, F, C> implements NVec<D, T>

hence,

• any FunVec<D1, T, F, C> implements V1<T>,
• any FunVec<D2, T, F, C> implements V2<T>,
• and so on.

Examples will hopefully clarify.

Examples

use orx_v::*;
use std::collections::HashMap;

#[derive(Clone, Copy)]
struct Geocode(i32, i32);

fn compute_using_coordinates<V: V1<Geocode>>(geocodes: V) { /* todo */ }

// we can pass a Vec of coordinates
compute_using_coordinates(&vec![Geocode(0, 0), Geocode(1, 1)]);

// or we can pass a functional vector
let geocodes = V.d1().fun(|[i]| Geocode(i as i32, i as i32));
compute_using_coordinates(geocodes);

// also see sparse (V.d1().sparse(Geocode(0, 0)))
let known_geocodes: HashMap<usize, Geocode> = [(3, Geocode(1, 1)), (7, Geocode(2, 1))].into_iter().collect();
let geocodes = V.d1().fun(|[i]| match known_geocodes.get(&i) {
    Some(geo) => *geo,
    None => Geocode(0, 0),
});
compute_using_coordinates(geocodes);

// the functional vectors are unbounded on construction
assert!(geocodes.is_unbounded());
assert_eq!(geocodes.card([]), usize::MAX);

The function of the functional geocodes vector can be anything that can compute a geocode based on its index. This is exactly the same in higher dimensional vectors.

If we break down all generic parameters:

• D = D1 since it is a 1-dimensional vector,
• T = Geocode which is the scalar that the vector returns,
• F is any function implementing Fn([usize; 1]) -> T, we can never type its name,
• C = UnboundedCard<D1>.

You might guess that, all functional vectors in the above examples are capable of computing a geocode for any given index. Their domains are unbounded; hence, the generic cardinality parameter is C = UnboundedCard<D1>. This makes sense at one hand; however, having a bounded domain is often more practical on the other hand. We can introduce bounds to the domain of the functional vector by using:

• bounded if the vector is of dimension D1,
• with_rectangular_bounds or with_variable_bounds otherwise.

Implementations

impl<T, F> FunVec<D1, T, F, UnboundedCard<D1>>

where F: Fn(<D1 as Dim>::Idx) -> T,

pub fn bounded(self, num_elements: usize) -> FunVec<D1, T, F, CardD1>

Converts an unbounded functional vector into one with a provided bound.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With bounded method, domain of the vector is defined.

Examples

use orx_v::*;

// [0, 10, 20, 30]
let v1 = V.d1().fun(|[i]| 10 * i as i32).bounded(4);

assert_eq!(v1.card([]), 4);
assert_eq!(v1.all().collect::<Vec<_>>(), vec![0, 10, 20, 30]);
assert_eq!(v1.equality(&[0, 10, 20, 30]), Equality::Equal);
assert_eq!(v1.all().sum::<i32>(), 60);

assert_eq!(v1.in_bounds([7]), false);
assert_eq!(v1.try_at([7]), None);
assert_eq!(v1.at([7]), 70); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

impl<T, F> FunVec<D2, T, F, UnboundedCard<D2>>

where F: Fn(<D2 as Dim>::Idx) -> T,

pub fn with_rectangular_bounds( self, dimensions: [usize; 2], ) -> FunVec<D2, T, F, RectangularCardD2>

Converts an unbounded functional vector into one with rectangular bounds as in matrices:

• the vector has dimensions[0] children, and
• each children has dimensions[1] elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// 2x3 => [ [0, 1, 2], [100, 101, 102] ]
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_rectangular_bounds([2, 3]);

assert_eq!(v2.card([]), 2);
assert_eq!(v2.card([0]), 3);
assert_eq!(v2.card([1]), 3);

assert_eq!(v2.at([1, 2]), 102);

assert_eq!(v2.all().collect::<Vec<_>>(), vec![0, 1, 2, 100, 101, 102]);

let row1 = v2.child(1);
assert_eq!(row1.card([]), 3);
assert_eq!(row1.at([0]), 100);
assert_eq!(row1.all().collect::<Vec<_>>(), vec![100, 101, 102]);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

pub fn with_variable_bounds<C>( self, cardinality: C, ) -> FunVec<D2, T, F, VariableCardD2<C>>

where C: V1<usize>,

Converts an unbounded functional vector into one with variable bounds as in jagged arrays:

• the vector has cardinality.card([]) children, and
• i-th child has cardinality.at([i]) elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// jagged => [ [0, 1], [100, 101, 102], [200] ]
let num_cols = vec![2, 3, 1];
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 3);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 1);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200]]),
    Equality::Equal,
);

// jagged => [ [0, 1], [100, 101, 102], [200, 201], [300, 301, 302] ]
let num_cols = V.d1().fun(|[i]| match i % 2 == 0 {
    true => 2,
    false => 3,
}).bounded(4);
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 4);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 2);
assert_eq!(v2.card([3]), 3);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200, 201], vec![300, 301, 302]]),
    Equality::Equal,
);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

impl<T, F> FunVec<D3, T, F, UnboundedCard<D3>>

where F: Fn(<D3 as Dim>::Idx) -> T,

pub fn with_rectangular_bounds( self, dimensions: [usize; 3], ) -> FunVec<D3, T, F, RectangularCardD3>

Converts an unbounded functional vector into one with rectangular bounds as in multi-dimensional matrices. The matrix has dimensions[0] x dimensions[1] x dimensions[2] elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// 2x3 => [ [0, 1, 2], [100, 101, 102] ]
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_rectangular_bounds([2, 3]);

assert_eq!(v2.card([]), 2);
assert_eq!(v2.card([0]), 3);
assert_eq!(v2.card([1]), 3);

assert_eq!(v2.at([1, 2]), 102);

assert_eq!(v2.all().collect::<Vec<_>>(), vec![0, 1, 2, 100, 101, 102]);

let row1 = v2.child(1);
assert_eq!(row1.card([]), 3);
assert_eq!(row1.at([0]), 100);
assert_eq!(row1.all().collect::<Vec<_>>(), vec![100, 101, 102]);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

pub fn with_variable_bounds<C>( self, cardinality: C, ) -> FunVec<D3, T, F, VariableCardD3<C>>

where C: V2<usize>,

Converts an unbounded functional vector into one with variable bounds as in jagged arrays:

• the vector has cardinality.card([]) children, and
• i-th child has cardinality.card([i]) children, and
• j-th child of the i-th child has cardinality.at([i, j]) elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// jagged => [ [0, 1], [100, 101, 102], [200] ]
let num_cols = vec![2, 3, 1];
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 3);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 1);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200]]),
    Equality::Equal,
);

// jagged => [ [0, 1], [100, 101, 102], [200, 201], [300, 301, 302] ]
let num_cols = V.d1().fun(|[i]| match i % 2 == 0 {
    true => 2,
    false => 3,
}).bounded(4);
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 4);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 2);
assert_eq!(v2.card([3]), 3);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200, 201], vec![300, 301, 302]]),
    Equality::Equal,
);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

impl<T, F> FunVec<D4, T, F, UnboundedCard<D4>>

where F: Fn(<D4 as Dim>::Idx) -> T,

pub fn with_rectangular_bounds( self, dimensions: [usize; 4], ) -> FunVec<D4, T, F, RectangularCardD4>

Converts an unbounded functional vector into one with rectangular bounds as in multi-dimensional matrices. The matrix has dimensions[0] x dimensions[1] x dimensions[2] x dimensions[3] elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// 2x3 => [ [0, 1, 2], [100, 101, 102] ]
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_rectangular_bounds([2, 3]);

assert_eq!(v2.card([]), 2);
assert_eq!(v2.card([0]), 3);
assert_eq!(v2.card([1]), 3);

assert_eq!(v2.at([1, 2]), 102);

assert_eq!(v2.all().collect::<Vec<_>>(), vec![0, 1, 2, 100, 101, 102]);

let row1 = v2.child(1);
assert_eq!(row1.card([]), 3);
assert_eq!(row1.at([0]), 100);
assert_eq!(row1.all().collect::<Vec<_>>(), vec![100, 101, 102]);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

pub fn with_variable_bounds<C>( self, cardinality: C, ) -> FunVec<D4, T, F, VariableCardD4<C>>

where C: V3<usize>,

Converts an unbounded functional vector into one with variable bounds as in jagged arrays:

• the vector has cardinality.card([]) children, and
• i-th child has cardinality.card([i]) children, and
• j-th child of the i-th child has cardinality.card([i, j]) children, and
• k-th child of the [i,j]-th child has cardinality.at([i, j, k]) elements.

Note that in practice, unbounded cardinality corresponds to a length of usize::MAX. One needs to be careful in using the all method which would iterate over the entire 0..usize::MAX range unless it is stopped on a condition such as in find method or limited by methods such as take.

With with_rectangular_bounds or with_variable_bounds methods, domain of the vector is defined.

Examples

use orx_v::*;

// jagged => [ [0, 1], [100, 101, 102], [200] ]
let num_cols = vec![2, 3, 1];
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 3);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 1);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200]]),
    Equality::Equal,
);

// jagged => [ [0, 1], [100, 101, 102], [200, 201], [300, 301, 302] ]
let num_cols = V.d1().fun(|[i]| match i % 2 == 0 {
    true => 2,
    false => 3,
}).bounded(4);
let v2 = V.d2().fun(|[i, j]| (100 * i + j) as i64).with_variable_bounds(num_cols);

assert_eq!(v2.card([]), 4);
assert_eq!(v2.card([0]), 2);
assert_eq!(v2.card([1]), 3);
assert_eq!(v2.card([2]), 2);
assert_eq!(v2.card([3]), 3);

assert_eq!(v2.at([0, 1]), 1);
assert_eq!(v2.at([1, 2]), 102);

assert_eq!(
    v2.equality(&[vec![0, 1], vec![100, 101, 102], vec![200, 201], vec![300, 301, 302]]),
    Equality::Equal,
);

assert_eq!(v2.in_bounds([100, 72]), false);
assert_eq!(v2.try_at([100, 72]), None);
assert_eq!(v2.at([100, 72]), 100 * 100 + 72); // (!) un-compromised performance

(!) un-compromised performance

Main reason to add bounds to a sparse vector is to set its domain. However, calling at with an out-of-bounds index can still produce a valid element in order not to compromise performance. If we want to check whether or not an index is in bounds or not, we can use the in_bounds or card methods, or use try_at instead which would return None if the index is out of bounds.

Trait Implementations

impl<D, T, F, C> Clone for FunVec<D, T, F, C>

where D: Dim, F: Fn(D::Idx) -> T + Clone, C: Card<D> + Clone,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T, F, C> Debug for FunVec<D1, T, F, C>

where F: Fn(<D1 as Dim>::Idx) -> T, C: Card<D1>, T: Debug, Self: NVec<D1, T>,

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

Formats the value using the given formatter.

impl<T, F, C> Debug for FunVec<D2, T, F, C>

where F: Fn(<D2 as Dim>::Idx) -> T, C: Card<D2>, T: Debug, Self: NVec<D2, T>,

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

Formats the value using the given formatter.

impl<T, F, C> Debug for FunVec<D3, T, F, C>

where F: Fn(<D3 as Dim>::Idx) -> T, C: Card<D3>, T: Debug, Self: NVec<D3, T>,

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

Formats the value using the given formatter.

impl<T, F, C> Debug for FunVec<D4, T, F, C>

where F: Fn(<D4 as Dim>::Idx) -> T, C: Card<D4>, T: Debug, Self: NVec<D4, T>,

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

Formats the value using the given formatter.

impl<D, T, F, C> IntoCached<D, T> for FunVec<D, T, F, C>

where D: Dim, F: Fn(D::Idx) -> T, C: Card<D>, T: Copy, D::Idx: Ord + Hash, Self: NVec<D, T>,

fn into_cached(self) -> CachedVec<D, T, Self, DefaultCache<D, T>>

Converts an NVec<D, T> into a cached vector which maintains an internal cache.

fn into_cached_with<C: Cache<D::Idx, T>>( self, cache: C, ) -> CachedVec<D, T, Self, C>

Converts an NVec<D, T> into a cached vector which maintains an internal cache.

impl<D, T, F, C> NVec<D, T> for FunVec<D, T, F, C>

where D: Dim, F: Fn(<D as Dim>::Idx) -> T, C: Card<D>,

fn at(&self, idx: impl IntoIdx<D>) -> T

Returns the element at the idx-th position of the vector.

fn child(&self, i: <D as Dim>::ChildIdx) -> impl NVec<<D as Dim>::PrevDim, T>

Returns the i-th child of the vector.

fn all(&self) -> impl Iterator<Item = T>

Returns a flattened iterator over all scalar (D0) elements of the vector.

fn num_children(&self) -> usize

Returns the number of children of the vector; i.e., number of elements of the one lower dimension.

fn card(&self, idx: impl Into<D::CardIdx>) -> usize

Returns the cardinality of the vec in any of the lower dimensions.

fn is_bounded(&self) -> bool

Returns whether or not the vector is bounded.

fn is_rectangular(&self) -> bool

Returns whether or not the cardinalities of the vector are rectangular. A rectangular vector of dimension D has the same number of children at a given lower dimension for all indices.

fn is_unbounded(&self) -> bool

Returns whether or not the vector is unbounded.

fn in_bounds(&self, idx: impl Into<D::LeqIdx>) -> bool

Returns whether or not the given idx is in bounds.

fn card_equality(&self, other: &impl NVec<D, T>) -> CardEquality<D>

Returns the cardinality equality of this vec with the other:

fn try_at(&self, idx: impl IntoIdx<D>) -> Option<T>

Returns the element at the idx-th position of the vector if the index is in_bounds; returns None otherwise.

fn equality(&self, other: &impl NVec<D, T>) -> Equality<D>

where T: PartialEq,

Returns the equality of this vec with the other:

fn children(&self) -> impl Iterator<Item = impl NVec<D::PrevDim, T>>

Returns an iterator of all children of the vector.

fn all_in( &self, indices: impl Iterator<Item = impl IntoIdx<D>>, ) -> impl Iterator<Item = T>

Returns an iterator of elements for the given indices.

impl<D, T: Copy, F, C> Copy for FunVec<D, T, F, C>

where D: Dim + Copy, F: Fn(D::Idx) -> T + Copy, C: Card<D> + Copy,