orx_v/v/
new_v3.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
use crate::{
    constant_vec::ConstantVec, empty_vec::EmptyVec, DefaultLookup, Dim, FunVec, Lookup, SparseVec,
    UnboundedCard, D3,
};

/// `V3<T>` (`NVec<D3, T>`) builder.
pub struct NewV3;

impl NewV3 {
    /// Creates a constant vector of dimension `D3` which returns the same value for any input index.
    ///
    /// Since a constant vector assumes all positions of the vector is filled with `value`, the
    /// vector on construction has [`UnboundedCard`]; i.e., it has a value for any possible index.
    ///
    /// In order to convert the constant vector into one with a provided bound, you may use the
    /// [`with_rectangular_bounds`] and [`with_variable_bounds`] methods.
    ///
    /// See [`V.d2().constant`] for examples.
    ///
    /// [`with_rectangular_bounds`]: `crate::ConstantVec::with_rectangular_bounds`
    /// [`with_variable_bounds`]: `crate::ConstantVec::with_variable_bounds`
    /// [`V.d2().constant`]: `crate::v::NewV2::constant`
    pub fn constant<T: Copy>(self, value: T) -> ConstantVec<D3, T, UnboundedCard<D3>> {
        ConstantVec::new(value, UnboundedCard::default())
    }

    /// Creates an empty vector of dimension `D3`.
    ///
    /// # Examples
    ///
    /// ```
    /// use orx_v::*;
    ///
    /// let v3 = V.d3().empty::<i32>();
    ///
    /// assert_eq!(v3.card([]), 0);
    /// assert_eq!(v3.in_bounds([0, 0, 0]), false);
    /// assert_eq!(v3.try_at([0, 0, 0]), None);
    /// assert_eq!(v3.all().next(), None);
    /// ```
    pub fn empty<T>(self) -> EmptyVec<D3, T> {
        Default::default()
    }

    /// Creates a sparse vector of dimension `D3` with an initially empty lookup.
    ///
    /// Sparse vectors maintain a (idx, value) lookup under the hood and has a `default_value`, and
    /// works as follows:
    /// * `at(idx)` returns the corresponding value if the idx exists in the lookup, or the default
    ///   value otherwise.
    /// * `at_mut(idx)` first adds `(idx, default_value)` to the lookup only if it is absent, and
    ///   returns a mutable reference to the value in the lookup.
    ///
    /// The objective of sparse vectors are to significantly reduce the memory requirement of vectors
    /// which has the same value for most of its positions. Consider for instance a 100x100 matrix
    /// which is all zeros except for the element at the (42,42)-th position which is 42. This matrix
    /// can be represented by a sparse vector with lookup containing only one element.
    ///
    /// Since sparse vector assumes all indices absent in the lookup have the `default_value`, the
    /// vector on construction has [`UnboundedCard`]; i.e., it has a value for any possible index.
    ///
    /// In order to convert the sparse vector into one with a provided bound, you may use the
    /// [`with_rectangular_bounds`] and [`with_variable_bounds`] methods.
    ///
    /// See [`V.d2().sparse`] for examples.
    ///
    /// [`V.d2().sparse`]: `crate::v::NewV2::sparse`
    /// [`with_rectangular_bounds`]: `crate::SparseVec::with_rectangular_bounds`
    /// [`with_variable_bounds`]: `crate::SparseVec::with_variable_bounds`
    pub fn sparse<T: Copy>(
        self,
        default_value: T,
    ) -> SparseVec<D3, T, UnboundedCard<D3>, DefaultLookup<D3, T>> {
        SparseVec::new(Default::default(), default_value, UnboundedCard::default())
    }

    /// Creates a sparse vector of dimension `D3` with the provided `lookup`.
    ///
    /// Sparse vectors maintain a (idx, value) lookup under the hood and has a `default_value`, and
    /// works as follows:
    /// * `at(idx)` returns the corresponding value if the idx exists in the lookup, or the default
    ///   value otherwise.
    /// * `at_mut(idx)` first adds `(idx, default_value)` to the lookup only if it is absent, and
    ///   returns a mutable reference to the value in the lookup.
    ///
    /// There might be alternative choices of the lookup type. It is required that the collection
    /// implements the [`Lookup`] trait. The std collection `HashMap` and no-std collection
    /// `BTreeMap` already implement this trait and can be readily be usd in sparse vectors.
    ///
    /// The objective of sparse vectors are to significantly reduce the memory requirement of vectors
    /// which has the same value for most of its positions. Consider for instance a 100x100 matrix
    /// which is all zeros except for the element at the (42,42)-th position which is 42. This matrix
    /// can be represented by a sparse vector with lookup containing only one element.
    ///
    /// Since sparse vector assumes all indices absent in the lookup have the `default_value`, the
    /// vector on construction has [`UnboundedCard`]; i.e., it has a value for any possible index.
    ///
    /// In order to convert the sparse vector into one with a provided bound, you may use the
    /// [`with_rectangular_bounds`] and [`with_variable_bounds`] methods.
    ///
    /// See [`V.d2().sparse_from`] for examples.
    ///
    /// [`V.d2().sparse_from`]: `crate::v::NewV2::sparse_from`
    /// [`with_rectangular_bounds`]: `crate::SparseVec::with_rectangular_bounds`
    /// [`with_variable_bounds`]: `crate::SparseVec::with_variable_bounds`
    pub fn sparse_from<T: Copy, L: Lookup<<D3 as Dim>::Idx, T>>(
        self,
        lookup: L,
        default_value: T,
    ) -> SparseVec<D3, T, UnboundedCard<D3>, L> {
        SparseVec::new(lookup, default_value, UnboundedCard::default())
    }

    /// Creates a functional vector of dimension `D3`.
    ///
    /// Since the functional vector is capable of creating an element for any given index, the vector
    /// on construction has [`UnboundedCard`]; i.e., it has a value for any possible index.
    ///
    /// In order to convert the sparse vector into one with a provided bound, you may use the
    /// [`with_rectangular_bounds`] and [`with_variable_bounds`] methods.
    ///
    /// See [`V.d2().fun`] for examples.
    ///
    /// [`V.d2().fun`]: `crate::v::NewV2::fun`
    /// [`with_rectangular_bounds`]: `crate::FunVec::with_rectangular_bounds`
    /// [`with_variable_bounds`]: `crate::FunVec::with_variable_bounds`
    pub fn fun<T, F>(self, at: F) -> FunVec<D3, T, F, UnboundedCard<D3>>
    where
        F: Fn(<D3 as Dim>::Idx) -> T,
    {
        FunVec::new(at, UnboundedCard::default())
    }
}