eryon-mem 0.0.4

this crate implements the memory-related aspects of the eryon framework
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
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183

/*
    appellation: indexer <module>
    authors: @FL03
*/
use super::types::{IndexMap, IndexSet};

/// the [`MemoryIndex`] is a dedicated indexing structure for the memory system, enabling
/// additional optimizations and quick access to features based on their dimensions, content,
/// and importance.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(
    feature = "serde",
    derive(serde_derive::Deserialize, serde_derive::Serialize),
    serde(default, rename_all = "snake_case")
)]
pub struct MemoryIndex {
    /// Features indexed by dimension for quick access
    pub(crate) dimension_index: IndexMap<usize, usize>,
    /// Features indexed by content
    pub(crate) content_index: IndexMap<Vec<usize>, usize>,
    /// Features indexed by importance (bucketed)
    pub(crate) importance_index: IndexMap<usize, usize>,
}

impl MemoryIndex {
    /// Creates a new `MemoryIndex` with empty indices.
    pub fn new() -> Self {
        MemoryIndex {
            dimension_index: IndexMap::new(),
            content_index: IndexMap::new(),
            importance_index: IndexMap::new(),
        }
    }
    /// returns an immutable reference to the dimension index.
    pub const fn dimension_index(&self) -> &IndexMap<usize, usize> {
        &self.dimension_index
    }
    /// returns a mutable reference to the dimension index.
    pub const fn dimension_index_mut(&mut self) -> &mut IndexMap<usize, usize> {
        &mut self.dimension_index
    }
    /// returns a reference to the content index.
    pub const fn content_index(&self) -> &IndexMap<Vec<usize>, usize> {
        &self.content_index
    }
    /// returns a mutable reference to the content index.
    pub const fn content_index_mut(&mut self) -> &mut IndexMap<Vec<usize>, usize> {
        &mut self.content_index
    }
    /// returns a reference to the importance index.
    pub const fn importance_index(&self) -> &IndexMap<usize, usize> {
        &self.importance_index
    }
    /// returns a mutable reference to the importance index.
    pub const fn importance_index_mut(&mut self) -> &mut IndexMap<usize, usize> {
        &mut self.importance_index
    }
    /// overrides the dimension index with a new one.
    pub fn set_dimension_index(&mut self, index: IndexMap<usize, usize>) -> &mut Self {
        self.dimension_index = index;
        self
    }
    /// overrides the content index with a new one.
    pub fn set_content_index(&mut self, index: IndexMap<Vec<usize>, usize>) -> &mut Self {
        self.content_index = index;
        self
    }
    /// overrides the importance index with a new one.
    pub fn set_importance_index(&mut self, index: IndexMap<usize, usize>) -> &mut Self {
        self.importance_index = index;
        self
    }
    /// consumes the current instance to create another with the given dimension index
    pub fn with_dimension_index(self, index: IndexMap<usize, usize>) -> Self {
        Self {
            dimension_index: index,
            ..self
        }
    }
    /// consumes the current instance to create another with the given content index
    pub fn with_content_index(self, index: IndexMap<Vec<usize>, usize>) -> Self {
        Self {
            content_index: index,
            ..self
        }
    }
    /// consumes the current instance to create another with the given importance index
    pub fn with_importance_index(self, index: IndexMap<usize, usize>) -> Self {
        Self {
            importance_index: index,
            ..self
        }
    }
    /// clears all indices.
    pub fn clear(&mut self) -> &mut Self {
        self.dimension_index.clear();
        self.content_index.clear();
        self.importance_index.clear();
        self
    }
    /// gets the number of entries in the dimension index.
    pub fn dimension_index_len(&self) -> usize {
        self.dimension_index().len()
    }
    /// gets the number of entries in the content index.
    pub fn content_index_len(&self) -> usize {
        self.content_index().len()
    }
    /// gets the number of entries in the importance index.
    pub fn importance_index_len(&self) -> usize {
        self.importance_index().len()
    }
    /// checks if the dimension index is empty.
    pub fn dimension_index_is_empty(&self) -> bool {
        self.dimension_index().is_empty()
    }
    /// checks if the content index is empty.
    pub fn content_index_is_empty(&self) -> bool {
        self.content_index().is_empty()
    }
    /// checks if the importance index is empty.
    pub fn importance_index_is_empty(&self) -> bool {
        self.importance_index().is_empty()
    }
    /// checks if all indices are empty.
    pub fn is_empty(&self) -> bool {
        self.dimension_index_is_empty()
            && self.content_index_is_empty()
            && self.importance_index_is_empty()
    }
    /// returns the total number of indexed features across all indices.
    pub fn total_indexed_features(&self) -> usize {
        self.dimension_index_len() + self.content_index_len() + self.importance_index_len()
    }
    /// retrieves the index of features for a given dimension key.
    pub fn get_dimension<Q>(&self, key: &Q) -> Option<&IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        usize: core::borrow::Borrow<Q>,
    {
        self.dimension_index().get(key)
    }
    /// retrieves a mutable index of features for a given dimension key.
    pub fn get_dimension_mut<Q>(&mut self, key: &Q) -> Option<&mut IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        usize: core::borrow::Borrow<Q>,
    {
        self.dimension_index_mut().get_mut(key)
    }
    /// retrieves the index of features for a given content key.
    pub fn get_content<Q>(&self, key: &Q) -> Option<&IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        Vec<usize>: core::borrow::Borrow<Q>,
    {
        self.content_index().get(key)
    }
    /// retrieves a mutable index of features for a given content key.
    pub fn get_content_mut<Q>(&mut self, key: &Q) -> Option<&mut IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        Vec<usize>: core::borrow::Borrow<Q>,
    {
        self.content_index_mut().get_mut(key)
    }
    /// retrieves the index of features for a given importance key.
    pub fn get_importance<Q>(&self, key: &Q) -> Option<&IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        usize: core::borrow::Borrow<Q>,
    {
        self.importance_index().get(key)
    }
    /// retrieves a mutable index of features for a given importance key.
    pub fn get_importance_mut<Q>(&mut self, key: &Q) -> Option<&mut IndexSet<usize>>
    where
        Q: Eq + core::hash::Hash,
        usize: core::borrow::Borrow<Q>,
    {
        self.importance_index_mut().get_mut(key)
    }
}