zerovec/map2d/
borrowed.rs

Help
1// This file is part of ICU4X. For terms of use, please see the file
2// called LICENSE at the top level of the ICU4X source tree
3// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ).
4
5use crate::ZeroSlice;
6
7use core::cmp::Ordering;
8use core::fmt;
9
10use crate::map::ZeroMapKV;
11use crate::map::ZeroVecLike;
12use crate::map2d::ZeroMap2dCursor;
13
14/// A borrowed-only version of [`ZeroMap2d`](super::ZeroMap2d)
15///
16/// This is useful for fully-zero-copy deserialization from non-human-readable
17/// serialization formats. It also has the advantage that it can return references that live for
18/// the lifetime of the backing buffer as opposed to that of the [`ZeroMap2dBorrowed`] instance.
19///
20/// # Examples
21///
22/// ```
23/// use zerovec::maps::ZeroMap2dBorrowed;
24///
25/// // Example byte buffer representing the map { 1: {2: "three" } }
26/// let BINCODE_BYTES: &[u8; 51] = &[
27///     2, 0, 0, 0, 0, 0, 0, 0, 1, 0, 4, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 2, 0,
28///     0, 0, 0, 0, 0, 0, 2, 0, 11, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 116,
29///     104, 114, 101, 101,
30/// ];
31///
32/// // Deserializing to ZeroMap2d requires no heap allocations.
33/// let zero_map: ZeroMap2dBorrowed<u16, u16, str> =
34///     bincode::deserialize(BINCODE_BYTES)
35///         .expect("Should deserialize successfully");
36/// assert_eq!(zero_map.get_2d(&1, &2), Some("three"));
37/// ```
38///
39/// This can be obtained from a [`ZeroMap2d`](super::ZeroMap2d) via [`ZeroMap2d::as_borrowed`](super::ZeroMap2d::as_borrowed)
40pub struct ZeroMap2dBorrowed<'a, K0, K1, V>
41where
42    K0: ZeroMapKV<'a>,
43    K1: ZeroMapKV<'a>,
44    V: ZeroMapKV<'a>,
45    K0: ?Sized,
46    K1: ?Sized,
47    V: ?Sized,
48{
49    pub(crate) keys0: &'a K0::Slice,
50    pub(crate) joiner: &'a ZeroSlice<u32>,
51    pub(crate) keys1: &'a K1::Slice,
52    pub(crate) values: &'a V::Slice,
53}
54
55impl<'a, K0, K1, V> Copy for ZeroMap2dBorrowed<'a, K0, K1, V>
56where
57    K0: ZeroMapKV<'a>,
58    K1: ZeroMapKV<'a>,
59    V: ZeroMapKV<'a>,
60    K0: ?Sized,
61    K1: ?Sized,
62    V: ?Sized,
63{
64}
65
66impl<'a, K0, K1, V> Clone for ZeroMap2dBorrowed<'a, K0, K1, V>
67where
68    K0: ZeroMapKV<'a>,
69    K1: ZeroMapKV<'a>,
70    V: ZeroMapKV<'a>,
71    K0: ?Sized,
72    K1: ?Sized,
73    V: ?Sized,
74{
75    fn clone(&self) -> Self {
76        *self
77    }
78}
79
80impl<'a, K0, K1, V> Default for ZeroMap2dBorrowed<'a, K0, K1, V>
81where
82    K0: ZeroMapKV<'a>,
83    K1: ZeroMapKV<'a>,
84    V: ZeroMapKV<'a>,
85    K0::Slice: 'static,
86    K1::Slice: 'static,
87    V::Slice: 'static,
88    K0: ?Sized,
89    K1: ?Sized,
90    V: ?Sized,
91{
92    fn default() -> Self {
93        Self::new()
94    }
95}
96
97impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
98where
99    K0: ZeroMapKV<'a>,
100    K1: ZeroMapKV<'a>,
101    V: ZeroMapKV<'a>,
102    K0::Slice: 'static,
103    K1::Slice: 'static,
104    V::Slice: 'static,
105    K0: ?Sized,
106    K1: ?Sized,
107    V: ?Sized,
108{
109    /// Creates a new, empty `ZeroMap2dBorrowed<K0, K1, V>`.
110    ///
111    /// Note: Since [`ZeroMap2dBorrowed`] is not mutable, the return value will be a stub unless
112    /// converted into a [`ZeroMap2d`](super::ZeroMap2d).
113    ///
114    /// # Examples
115    ///
116    /// ```
117    /// use zerovec::maps::ZeroMap2dBorrowed;
118    ///
119    /// let zm: ZeroMap2dBorrowed<u16, u16, str> = ZeroMap2dBorrowed::new();
120    /// assert!(zm.is_empty());
121    /// ```
122    pub fn new() -> Self {
123        Self {
124            keys0: K0::Container::zvl_new_borrowed(),
125            joiner: Default::default(),
126            keys1: K1::Container::zvl_new_borrowed(),
127            values: V::Container::zvl_new_borrowed(),
128        }
129    }
130}
131
132impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
133where
134    K0: ZeroMapKV<'a>,
135    K1: ZeroMapKV<'a>,
136    V: ZeroMapKV<'a>,
137    K0: ?Sized,
138    K1: ?Sized,
139    V: ?Sized,
140{
141    #[doc(hidden)] // databake internal
142    pub const unsafe fn from_parts_unchecked(
143        keys0: &'a K0::Slice,
144        joiner: &'a ZeroSlice<u32>,
145        keys1: &'a K1::Slice,
146        values: &'a V::Slice,
147    ) -> Self {
148        Self {
149            keys0,
150            joiner,
151            keys1,
152            values,
153        }
154    }
155
156    /// The number of elements in the [`ZeroMap2dBorrowed`]
157    pub fn len(&self) -> usize {
158        self.values.zvl_len()
159    }
160
161    /// Whether the [`ZeroMap2dBorrowed`] is empty
162    pub fn is_empty(&self) -> bool {
163        self.values.zvl_len() == 0
164    }
165}
166
167impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
168where
169    K0: ZeroMapKV<'a> + Ord,
170    K1: ZeroMapKV<'a> + Ord,
171    V: ZeroMapKV<'a>,
172    K0: ?Sized,
173    K1: ?Sized,
174    V: ?Sized,
175{
176    /// Get the value associated with `key0` and `key1`, if it exists.
177    ///
178    /// This is able to return values that live longer than the map itself
179    /// since they borrow directly from the backing buffer. This is the
180    /// primary advantage of using [`ZeroMap2dBorrowed`](super::ZeroMap2dBorrowed) over [`ZeroMap2d`](super::ZeroMap2d).
181    ///
182    /// ```rust
183    /// use zerovec::ZeroMap2d;
184    ///
185    /// let mut map = ZeroMap2d::new();
186    /// map.insert(&1, "one", "foo");
187    /// map.insert(&2, "one", "bar");
188    /// map.insert(&2, "two", "baz");
189    ///
190    /// let borrowed = map.as_borrowed();
191    /// assert_eq!(borrowed.get_2d(&1, "one"), Some("foo"));
192    /// assert_eq!(borrowed.get_2d(&1, "two"), None);
193    /// assert_eq!(borrowed.get_2d(&2, "one"), Some("bar"));
194    /// assert_eq!(borrowed.get_2d(&2, "two"), Some("baz"));
195    /// assert_eq!(borrowed.get_2d(&3, "three"), None);
196    /// ```
197    pub fn get_2d(&self, key0: &K0, key1: &K1) -> Option<&'a V::GetType> {
198        self.get0(key0)?.get1(key1)
199    }
200}
201
202impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
203where
204    K0: ZeroMapKV<'a> + Ord,
205    K1: ZeroMapKV<'a>,
206    V: ZeroMapKV<'a>,
207    K0: ?Sized,
208    K1: ?Sized,
209    V: ?Sized,
210{
211    /// Gets a cursor for `key0`. If `None`, then `key0` is not in the map. If `Some`,
212    /// then `key0` is in the map, and `key1` can be queried.
213    ///
214    /// ```rust
215    /// use zerovec::ZeroMap2d;
216    ///
217    /// let mut map = ZeroMap2d::new();
218    /// map.insert(&1, "one", "foo");
219    /// map.insert(&2, "two", "bar");
220    /// let borrowed = map.as_borrowed();
221    /// assert!(matches!(borrowed.get0(&1), Some(_)));
222    /// assert!(matches!(borrowed.get0(&3), None));
223    /// ```
224    #[inline]
225    pub fn get0<'l>(&'l self, key0: &K0) -> Option<ZeroMap2dCursor<'a, 'a, K0, K1, V>> {
226        let key0_index = self.keys0.zvl_binary_search(key0).ok()?;
227        Some(ZeroMap2dCursor::from_borrowed(self, key0_index))
228    }
229
230    /// Binary search the map for `key0`, returning a cursor.
231    ///
232    /// ```rust
233    /// use zerovec::ZeroMap2d;
234    ///
235    /// let mut map = ZeroMap2d::new();
236    /// map.insert(&1, "one", "foo");
237    /// map.insert(&2, "two", "bar");
238    /// let borrowed = map.as_borrowed();
239    /// assert!(matches!(borrowed.get0_by(|probe| probe.cmp(&1)), Some(_)));
240    /// assert!(matches!(borrowed.get0_by(|probe| probe.cmp(&3)), None));
241    /// ```
242    pub fn get0_by<'l>(
243        &'l self,
244        predicate: impl FnMut(&K0) -> Ordering,
245    ) -> Option<ZeroMap2dCursor<'a, 'a, K0, K1, V>> {
246        let key0_index = self.keys0.zvl_binary_search_by(predicate).ok()?;
247        Some(ZeroMap2dCursor::from_borrowed(self, key0_index))
248    }
249
250    /// Returns whether `key0` is contained in this map
251    ///
252    /// ```rust
253    /// use zerovec::ZeroMap2d;
254    ///
255    /// let mut map = ZeroMap2d::new();
256    /// map.insert(&1, "one", "foo");
257    /// map.insert(&2, "two", "bar");
258    /// let borrowed = map.as_borrowed();
259    /// assert!(borrowed.contains_key0(&1));
260    /// assert!(!borrowed.contains_key0(&3));
261    /// ```
262    pub fn contains_key0(&self, key0: &K0) -> bool {
263        self.keys0.zvl_binary_search(key0).is_ok()
264    }
265}
266
267impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
268where
269    K0: ZeroMapKV<'a>,
270    K1: ZeroMapKV<'a>,
271    V: ZeroMapKV<'a>,
272    K0: ?Sized,
273    K1: ?Sized,
274    V: ?Sized,
275{
276    /// Produce an ordered iterator over keys0
277    pub fn iter0<'l>(&'l self) -> impl Iterator<Item = ZeroMap2dCursor<'a, 'a, K0, K1, V>> + '_ {
278        (0..self.keys0.zvl_len()).map(move |idx| ZeroMap2dCursor::from_borrowed(self, idx))
279    }
280}
281
282impl<'a, K0, K1, V> ZeroMap2dBorrowed<'a, K0, K1, V>
283where
284    K0: ZeroMapKV<'a> + Ord,
285    K1: ZeroMapKV<'a> + Ord,
286    V: ZeroMapKV<'a>,
287    V: Copy,
288    K0: ?Sized,
289    K1: ?Sized,
290{
291    /// For cases when `V` is fixed-size, obtain a direct copy of `V` instead of `V::ULE`
292    pub fn get_copied_2d(&self, key0: &K0, key1: &K1) -> Option<V> {
293        self.get0(key0)?.get1_copied(key1)
294    }
295}
296
297// We can't use the default PartialEq because ZeroMap2d is invariant
298// so otherwise rustc will not automatically allow you to compare ZeroMaps
299// with different lifetimes
300impl<'a, 'b, K0, K1, V> PartialEq<ZeroMap2dBorrowed<'b, K0, K1, V>>
301    for ZeroMap2dBorrowed<'a, K0, K1, V>
302where
303    K0: for<'c> ZeroMapKV<'c> + ?Sized,
304    K1: for<'c> ZeroMapKV<'c> + ?Sized,
305    V: for<'c> ZeroMapKV<'c> + ?Sized,
306    <K0 as ZeroMapKV<'a>>::Slice: PartialEq<<K0 as ZeroMapKV<'b>>::Slice>,
307    <K1 as ZeroMapKV<'a>>::Slice: PartialEq<<K1 as ZeroMapKV<'b>>::Slice>,
308    <V as ZeroMapKV<'a>>::Slice: PartialEq<<V as ZeroMapKV<'b>>::Slice>,
309{
310    fn eq(&self, other: &ZeroMap2dBorrowed<'b, K0, K1, V>) -> bool {
311        self.keys0.eq(other.keys0)
312            && self.joiner.eq(other.joiner)
313            && self.keys1.eq(other.keys1)
314            && self.values.eq(other.values)
315    }
316}
317
318impl<'a, K0, K1, V> fmt::Debug for ZeroMap2dBorrowed<'a, K0, K1, V>
319where
320    K0: ZeroMapKV<'a> + ?Sized,
321    K1: ZeroMapKV<'a> + ?Sized,
322    V: ZeroMapKV<'a> + ?Sized,
323    K0::Slice: fmt::Debug,
324    K1::Slice: fmt::Debug,
325    V::Slice: fmt::Debug,
326{
327    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> {
328        f.debug_struct("ZeroMap2dBorrowed")
329            .field("keys0", &self.keys0)
330            .field("joiner", &self.joiner)
331            .field("keys1", &self.keys1)
332            .field("values", &self.values)
333            .finish()
334    }
335}
zerovec/map2d/borrowed.rs

zerovec/map2d/
borrowed.rs
