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

zrx_stream/stream/value/
collection.rs
