zrx_stream/stream/value/
collection.rs

1// Copyright (c) 2025 Zensical and contributors
2
3// SPDX-License-Identifier: MIT
4// Third-party contributions licensed under 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//! Collection of items.
27
28use std::any::Any;
29use std::fmt::Debug;
30
31use zrx_scheduler::{Id, Value};
32use zrx_store::{Store, StoreIterable, StoreKeys, StoreValues};
33
34// ----------------------------------------------------------------------------
35// Traits
36// ----------------------------------------------------------------------------
37
38/// Collection of items.
39///
40/// This data type combines the most common traits from our store abstractions
41/// into a single trait that is _dyn-compatible_, so it can be used in operator
42/// functions to erase the concrete store type, which is central to hiding the
43/// implementation details of operators.
44///
45/// In order to automatically implement the [`Value`] trait for all data types
46/// that implement [`Store`] and friends, we must implement [`Value`] on the
47/// trait object `dyn Collection<I, T>`. Thus, we must require the supertraits
48/// of [`Value`] on this trait, and for the blanket implementation. In case more
49/// supertraits are added to [`Value`] in the future, we must add them here as
50/// well, which is however unlikely to happen.
51pub trait Collection<I, T>: Any + Debug + Send {
52    /// Returns a reference to the value identified by the key.
53    fn get(&self, id: &I) -> Option<&T>;
54
55    /// Returns whether the collection contains the key.
56    fn contains_key(&self, id: &I) -> bool;
57
58    /// Returns the number of items in the collection.
59    fn len(&self) -> usize;
60
61    /// Returns whether the collection is empty.
62    fn is_empty(&self) -> bool;
63
64    /// Creates an iterator over the store.
65    fn iter(&self) -> Iter<'_, I, T>;
66
67    /// Creates a key iterator over the store.
68    fn keys(&self) -> Keys<'_, I>;
69
70    /// Creates a value iterator over the store.
71    fn values(&self) -> Values<'_, T>;
72}
73
74// ----------------------------------------------------------------------------
75// Trait implementations
76// ----------------------------------------------------------------------------
77
78impl<I, T> Value for dyn Collection<I, T>
79where
80    I: Id,
81    T: Value,
82{
83}
84
85// ----------------------------------------------------------------------------
86// Blanket implementations
87// ----------------------------------------------------------------------------
88
89impl<I, T, S> Collection<I, T> for S
90where
91    I: Id,
92    T: Value,
93    S: Any + Debug + Send,
94    S: Store<I, T> // fmt
95        + StoreIterable<I, T>
96        + StoreKeys<I, T>
97        + StoreValues<I, T>,
98{
99    /// Returns a reference to the value identified by the key.
100    #[inline]
101    fn get(&self, id: &I) -> Option<&T> {
102        Store::get(self, id)
103    }
104
105    /// Returns whether the collection contains the key.
106    #[inline]
107    fn contains_key(&self, id: &I) -> bool {
108        Store::contains_key(self, id)
109    }
110
111    /// Returns the number of items in the collection.
112    #[inline]
113    fn len(&self) -> usize {
114        Store::len(self)
115    }
116
117    /// Creates an iterator over the store.
118    #[inline]
119    fn is_empty(&self) -> bool {
120        Store::is_empty(self)
121    }
122
123    /// Creates an iterator over the store.
124    #[inline]
125    fn iter(&self) -> Iter<'_, I, T> {
126        Box::new(StoreIterable::iter(self))
127    }
128
129    /// Creates a key iterator over the store.
130    #[inline]
131    fn keys(&self) -> Keys<'_, I> {
132        Box::new(StoreKeys::keys(self))
133    }
134
135    /// Creates a value iterator over the store.
136    #[inline]
137    fn values(&self) -> Values<'_, T> {
138        Box::new(StoreValues::values(self))
139    }
140}
141
142// ----------------------------------------------------------------------------
143// Type aliases
144// ----------------------------------------------------------------------------
145
146/// Collection iterator.
147type Iter<'a, I, T> = Box<dyn Iterator<Item = (&'a I, &'a T)> + 'a>;
148
149/// Collection key iterator.
150type Keys<'a, I> = Box<dyn Iterator<Item = &'a I> + 'a>;
151
152/// Collection value iterator.
153type Values<'a, T> = Box<dyn Iterator<Item = &'a T> + 'a>;
zrx_stream/stream/value/collection.rs

zrx_stream/stream/value/
collection.rs
