zrx_store/stash/iter.rs
1// Copyright (c) 2025-2026 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// All contributions are certified under the DCO
5
6// Permission is hereby granted, free of charge, to any person obtaining a copy
7// of this software and associated documentation files (the "Software"), to
8// deal in the Software without restriction, including without limitation the
9// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
10// sell copies of the Software, and to permit persons to whom the Software is
11// furnished to do so, subject to the following conditions:
12
13// The above copyright notice and this permission notice shall be included in
14// all copies or substantial portions of the Software.
15
16// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
19// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
22// IN THE SOFTWARE.
23
24// ----------------------------------------------------------------------------
25
26//! Iterator implementations for [`Stash`].
27
28use crate::store::adapter::slab::{Iter, IterMut, Keys, Values};
29use crate::store::item::{Key, Value};
30use crate::store::{StoreIterable, StoreIterableMut, StoreKeys, StoreValues};
31
32use super::Stash;
33
34// ----------------------------------------------------------------------------
35// Structs
36// ----------------------------------------------------------------------------
37
38/// Iterator over the slots of a [`Stash`].
39#[derive(Debug)]
40pub struct Slots<'a, K, V> {
41 /// Inner iterator.
42 inner: slab::Iter<'a, (K, V)>,
43}
44
45/// Mutable iterator over the slots of a [`Stash`].
46#[derive(Debug)]
47pub struct SlotsMut<'a, K, V> {
48 /// Inner iterator.
49 inner: slab::IterMut<'a, (K, V)>,
50}
51
52// ----------------------------------------------------------------------------
53// Implementations
54// ----------------------------------------------------------------------------
55
56impl<K, V, S> Stash<K, V, S> {
57 /// Creates an iterator over the slots of the stash.
58 ///
59 /// # Examples
60 ///
61 /// ```
62 /// use zrx_store::Stash;
63 ///
64 /// // Create stash and initial state
65 /// let mut stash = Stash::default();
66 /// stash.insert("key", 42);
67 ///
68 /// // Create iterator over the stash
69 /// for (index, (key, value)) in stash.slots() {
70 /// println!("[{index}] {key}: {value}");
71 /// }
72 /// ```
73 #[inline]
74 #[must_use]
75 pub fn slots(&self) -> Slots<'_, K, V> {
76 Slots { inner: self.items.iter() }
77 }
78
79 /// Creates a mutable iterator over the slots of the stash.
80 ///
81 /// # Examples
82 ///
83 /// ```
84 /// use zrx_store::Stash;
85 ///
86 /// // Create stash and initial state
87 /// let mut stash = Stash::default();
88 /// stash.insert("key", 42);
89 ///
90 /// // Create iterator over the stash
91 /// for (index, (key, value)) in stash.slots_mut() {
92 /// println!("[{index}] {key}: {value}");
93 /// }
94 /// ```
95 #[inline]
96 #[must_use]
97 pub fn slots_mut(&mut self) -> SlotsMut<'_, K, V> {
98 SlotsMut { inner: self.items.iter_mut() }
99 }
100}
101
102// ----------------------------------------------------------------------------
103// Trait implementations
104// ----------------------------------------------------------------------------
105
106impl<K, V, S> StoreIterable<K, V> for Stash<K, V, S>
107where
108 K: Key,
109 V: Value,
110 S: StoreIterable<K, usize>,
111{
112 type Iter<'a> = Iter<'a, K, V>
113 where
114 Self: 'a;
115
116 /// Creates an iterator over the items of the stash.
117 ///
118 /// # Examples
119 ///
120 /// ```
121 /// use zrx_store::{Stash, StoreIterable};
122 ///
123 /// // Create stash and initial state
124 /// let mut stash = Stash::default();
125 /// stash.insert("key", 42);
126 ///
127 /// // Create iterator over the stash
128 /// for (key, value) in stash.iter() {
129 /// println!("{key}: {value}");
130 /// }
131 /// ```
132 #[inline]
133 fn iter(&self) -> Self::Iter<'_> {
134 StoreIterable::iter(&self.items)
135 }
136}
137
138impl<K, V, S> StoreIterableMut<K, V> for Stash<K, V, S>
139where
140 K: Key,
141 V: Value,
142 S: StoreIterableMut<K, usize>,
143{
144 type IterMut<'a> = IterMut<'a, K, V>
145 where
146 Self: 'a;
147
148 /// Creates a mutable iterator over the items of the stash.
149 ///
150 /// # Examples
151 ///
152 /// ```
153 /// use zrx_store::{Stash, StoreIterableMut};
154 ///
155 /// // Create stash and initial state
156 /// let mut stash = Stash::default();
157 /// stash.insert("key", 42);
158 ///
159 /// // Create iterator over the stash
160 /// for (key, value) in stash.iter_mut() {
161 /// println!("{key}: {value}");
162 /// }
163 /// ```
164 #[inline]
165 fn iter_mut(&mut self) -> Self::IterMut<'_> {
166 StoreIterableMut::iter_mut(&mut self.items)
167 }
168}
169
170impl<K, V, S> StoreKeys<K, V> for Stash<K, V, S>
171where
172 K: Key,
173 S: StoreKeys<K, usize>,
174{
175 type Keys<'a> = Keys<'a, K, V>
176 where
177 Self: 'a;
178
179 /// Creates an iterator over the keys of the stash.
180 ///
181 /// # Examples
182 ///
183 /// ```
184 /// use zrx_store::{Stash, StoreKeys};
185 ///
186 /// // Create stash and initial state
187 /// let mut stash = Stash::default();
188 /// stash.insert("key", 42);
189 ///
190 /// // Create iterator over the stash
191 /// for key in stash.keys() {
192 /// println!("{key}");
193 /// }
194 /// ```
195 #[inline]
196 fn keys(&self) -> Self::Keys<'_> {
197 StoreKeys::keys(&self.items)
198 }
199}
200
201impl<K, V, S> StoreValues<K, V> for Stash<K, V, S>
202where
203 K: Key,
204 V: Value,
205 S: StoreValues<K, usize>,
206{
207 type Values<'a> = Values<'a, K, V>
208 where
209 Self: 'a;
210
211 /// Creates an iterator over the values of the stash.
212 ///
213 /// # Examples
214 ///
215 /// ```
216 /// use zrx_store::{Stash, StoreValues};
217 ///
218 /// // Create stash and initial state
219 /// let mut stash = Stash::default();
220 /// stash.insert("key", 42);
221 ///
222 /// // Create iterator over the stash
223 /// for value in stash.values() {
224 /// println!("{value}");
225 /// }
226 /// ```
227 #[inline]
228 fn values(&self) -> Self::Values<'_> {
229 StoreValues::values(&self.items)
230 }
231}
232
233// ----------------------------------------------------------------------------
234
235impl<'a, K, V> Iterator for Slots<'a, K, V> {
236 type Item = (usize, (&'a K, &'a V));
237
238 /// Returns the next item.
239 #[inline]
240 fn next(&mut self) -> Option<Self::Item> {
241 let opt = self.inner.next();
242 opt.map(|(index, (key, value))| (index, (key, value)))
243 }
244
245 /// Returns the bounds on the remaining length of the iterator.
246 #[inline]
247 fn size_hint(&self) -> (usize, Option<usize>) {
248 self.inner.size_hint()
249 }
250}
251
252impl<K, V> ExactSizeIterator for Slots<'_, K, V> {
253 /// Returns the exact remaining length of the iterator.
254 #[inline]
255 fn len(&self) -> usize {
256 self.inner.len()
257 }
258}
259
260// ----------------------------------------------------------------------------
261
262impl<'a, K, V> Iterator for SlotsMut<'a, K, V> {
263 type Item = (usize, (&'a K, &'a mut V));
264
265 /// Returns the next item.
266 #[inline]
267 fn next(&mut self) -> Option<Self::Item> {
268 let opt = self.inner.next();
269 opt.map(|(index, (key, value))| (index, (&*key, value)))
270 }
271
272 /// Returns the bounds on the remaining length of the iterator.
273 #[inline]
274 fn size_hint(&self) -> (usize, Option<usize>) {
275 self.inner.size_hint()
276 }
277}
278
279impl<K, V> ExactSizeIterator for SlotsMut<'_, K, V> {
280 /// Returns the exact remaining length of the iterator.
281 #[inline]
282 fn len(&self) -> usize {
283 self.inner.len()
284 }
285}