spinoso_symbol/
all_symbols.rs

1use core::iter::FusedIterator;
2use core::ops::Range;
3
4use artichoke_core::intern::Intern;
5
6use crate::Symbol;
7
8/// Extension trait to return an iterator that returns all symbol identifiers
9/// stored in an [interner] as [`Symbol`]s.
10///
11/// The returned iterator yields [`Symbol`] as its item type.
12///
13/// Implementers of this trait must issue symbol identifiers as an [arithmetic
14/// progression] with a common difference of 1. The sequence of symbol
15/// identifiers must be representable by a [`Range<u32>`].
16///
17/// This trait is automatically implemented for all types that implement
18/// [`Intern`] from [`artichoke_core`].
19///
20/// # Examples
21///
22/// ```
23/// # extern crate alloc;
24/// use alloc::borrow::Cow;
25/// use alloc::boxed::Box;
26///
27/// use artichoke_core::intern::Intern;
28/// use spinoso_symbol::{InternerAllSymbols, Symbol};
29///
30/// #[derive(Default)]
31/// struct Interner(u32);
32///
33/// impl Intern for Interner {
34///     type Symbol = u32;
35///     type Error = &'static str;
36///     const SYMBOL_RANGE_START: u32 = 1;
37///
38///     fn intern_bytes<T>(&mut self, symbol: T) -> Result<Self::Symbol, Self::Error>
39///     where
40///         T: Into<Cow<'static, [u8]>>,
41///     {
42///         let boxed = Box::<[u8]>::from(symbol.into());
43///         Box::leak(boxed);
44///         self.0 += 1;
45///         let sym = self.0;
46///         Ok(sym)
47///     }
48///
49///     fn check_interned_bytes(&self, symbol: &[u8]) -> Result<Option<Self::Symbol>, Self::Error> {
50///         Err("not implemented")
51///     }
52///
53///     fn lookup_symbol(&self, symbol: Self::Symbol) -> Result<Option<&[u8]>, Self::Error> {
54///         Err("not implemented")
55///     }
56///
57///     fn symbol_count(&self) -> usize {
58///         self.0 as usize
59///     }
60/// }
61///
62/// let mut interner = Interner::default();
63/// let mut all_symbols = interner.all_symbols();
64/// assert_eq!(all_symbols.count(), 0);
65///
66/// interner.intern_bytes(&b"Spinoso"[..]);
67/// interner.intern_bytes(&b"Artichoke"[..]);
68///
69/// let mut all_symbols = interner.all_symbols();
70/// assert_eq!(all_symbols.next(), Some(Symbol::new(1)));
71/// assert_eq!(all_symbols.next(), Some(Symbol::new(2)));
72/// assert_eq!(all_symbols.next(), None);
73/// ```
74///
75/// [interner]: Intern
76/// [arithmetic progression]: https://en.wikipedia.org/wiki/Arithmetic_progression
77/// [`Range<u32>`]: core::ops::Range
78#[cfg_attr(docsrs, doc(cfg(feature = "artichoke")))]
79pub trait InternerAllSymbols: Intern {
80    /// Returns an iterator that returns all symbol identifiers stored in an
81    /// [interner] as [`Symbol`]s.
82    ///
83    /// The returned iterator yields [`Symbol`] as its item type.
84    ///
85    /// This function requires that the interner issues symbol identifiers as an
86    /// [arithmetic progression] with a common difference of 1. The sequence of
87    /// symbol identifiers must be representable by a [`Range<u32>`].
88    ///
89    /// [`AllSymbols`] supports yielding up to `u32::MAX - 1` `Symbol`s.
90    ///
91    /// # Examples
92    ///
93    /// See trait-level documentation for examples.
94    ///
95    /// [interner]: Intern
96    /// [arithmetic progression]: https://en.wikipedia.org/wiki/Arithmetic_progression
97    /// [`Range<u32>`]: core::ops::Range
98    fn all_symbols(&self) -> AllSymbols;
99}
100
101impl<T, U> InternerAllSymbols for T
102where
103    T: Intern<Symbol = U>,
104    U: Copy + Into<u32>,
105{
106    #[inline]
107    #[cfg_attr(docsrs, doc(cfg(feature = "artichoke")))]
108    fn all_symbols(&self) -> AllSymbols {
109        self.into()
110    }
111}
112
113impl<T, U> From<&T> for AllSymbols
114where
115    T: Intern<Symbol = U>,
116    U: Copy + Into<u32>,
117{
118    /// Construct a [`AllSymbols`] iterator from an interner.
119    #[inline]
120    fn from(interner: &T) -> Self {
121        let min = T::SYMBOL_RANGE_START.into();
122        let max_idx = interner.symbol_count().try_into().unwrap_or(u32::MAX);
123        let max = min.saturating_add(max_idx);
124        AllSymbols(min..max)
125    }
126}
127
128/// An iterator that returns all the Symbols in an [interner].
129///
130/// This iterator yields [`Symbol`] as its item type.
131///
132/// This iterator supports yielding up to `u32::MAX - 1` `Symbol`s.
133///
134/// This struct is created by the [`all_symbols`] method in the
135/// [`InternerAllSymbols`] trait.  See its documentation for more.
136///
137/// [interner]: Intern
138/// [`all_symbols`]: InternerAllSymbols::all_symbols
139#[derive(Debug, Clone, Hash, PartialEq, Eq)]
140#[must_use = "this `AllSymbols` is an `Iterator`, which should be consumed if constructed"]
141#[cfg_attr(docsrs, doc(cfg(feature = "artichoke")))]
142pub struct AllSymbols(Range<u32>);
143
144impl Iterator for AllSymbols {
145    type Item = Symbol;
146
147    #[inline]
148    fn next(&mut self) -> Option<Self::Item> {
149        self.0.next().map(Symbol::from)
150    }
151
152    #[inline]
153    fn nth(&mut self, n: usize) -> Option<Self::Item> {
154        self.0.nth(n).map(Symbol::from)
155    }
156
157    #[inline]
158    fn count(self) -> usize {
159        // Inline implementation of `Step::steps_between` since
160        // `<Range as Iterator>::count` is not specialized to use it for integer
161        // ranges.
162        if self.0.start <= self.0.end {
163            (self.0.end - self.0.start) as usize
164        } else {
165            0
166        }
167    }
168
169    #[inline]
170    fn size_hint(&self) -> (usize, Option<usize>) {
171        self.0.size_hint()
172    }
173
174    #[inline]
175    fn last(self) -> Option<Self::Item> {
176        self.0.last().map(Symbol::from)
177    }
178
179    #[inline]
180    fn min(mut self) -> Option<Self::Item> {
181        self.0.next().map(Symbol::from)
182    }
183
184    #[inline]
185    fn max(self) -> Option<Self::Item> {
186        self.0.max().map(Symbol::from)
187    }
188}
189
190impl DoubleEndedIterator for AllSymbols {
191    #[inline]
192    fn next_back(&mut self) -> Option<Self::Item> {
193        self.0.next_back().map(Symbol::from)
194    }
195
196    #[inline]
197    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
198        self.0.nth_back(n).map(Symbol::from)
199    }
200}
201
202impl ExactSizeIterator for AllSymbols {}
203
204impl FusedIterator for AllSymbols {}
205
206#[cfg(test)]
207mod tests {
208    use std::borrow::Cow;
209
210    use artichoke_core::intern::Intern;
211
212    use super::InternerAllSymbols;
213    use crate::Symbol;
214
215    #[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
216    struct Interner(u32);
217
218    impl Intern for Interner {
219        type Symbol = u32;
220        type Error = &'static str;
221        const SYMBOL_RANGE_START: Self::Symbol = 0;
222
223        fn intern_bytes<T>(&mut self, symbol: T) -> Result<Self::Symbol, Self::Error>
224        where
225            T: Into<Cow<'static, [u8]>>,
226        {
227            drop(symbol.into());
228            Err("not implemented")
229        }
230
231        fn check_interned_bytes(&self, _symbol: &[u8]) -> Result<Option<Self::Symbol>, Self::Error> {
232            Err("not implemented")
233        }
234
235        fn lookup_symbol(&self, _symbol: Self::Symbol) -> Result<Option<&[u8]>, Self::Error> {
236            Err("not implemented")
237        }
238
239        fn symbol_count(&self) -> usize {
240            self.0 as usize
241        }
242    }
243
244    #[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
245    struct OffByOneInterner(u32);
246
247    impl Intern for OffByOneInterner {
248        type Symbol = u32;
249        type Error = &'static str;
250        const SYMBOL_RANGE_START: Self::Symbol = 1;
251
252        fn intern_bytes<T>(&mut self, symbol: T) -> Result<Self::Symbol, Self::Error>
253        where
254            T: Into<Cow<'static, [u8]>>,
255        {
256            drop(symbol.into());
257            Err("not implemented")
258        }
259
260        fn check_interned_bytes(&self, _symbol: &[u8]) -> Result<Option<Self::Symbol>, Self::Error> {
261            Err("not implemented")
262        }
263
264        fn lookup_symbol(&self, _symbol: Self::Symbol) -> Result<Option<&[u8]>, Self::Error> {
265            Err("not implemented")
266        }
267
268        fn symbol_count(&self) -> usize {
269            self.0 as usize
270        }
271    }
272
273    #[derive(Default, Debug, Clone, Copy, Hash, PartialEq, Eq, PartialOrd, Ord)]
274    struct NonZeroInterner(u32);
275
276    impl Intern for NonZeroInterner {
277        type Symbol = u32;
278        type Error = &'static str;
279        const SYMBOL_RANGE_START: Self::Symbol = u32::MAX - 16;
280
281        fn intern_bytes<T>(&mut self, symbol: T) -> Result<Self::Symbol, Self::Error>
282        where
283            T: Into<Cow<'static, [u8]>>,
284        {
285            drop(symbol.into());
286            Err("not implemented")
287        }
288
289        fn check_interned_bytes(&self, _symbol: &[u8]) -> Result<Option<Self::Symbol>, Self::Error> {
290            Err("not implemented")
291        }
292
293        fn lookup_symbol(&self, _symbol: Self::Symbol) -> Result<Option<&[u8]>, Self::Error> {
294            Err("not implemented")
295        }
296
297        fn symbol_count(&self) -> usize {
298            self.0 as usize
299        }
300    }
301
302    #[test]
303    fn zero_offset_count() {
304        let interner = Interner::default();
305        let all_symbols = interner.all_symbols();
306        assert_eq!(all_symbols.count(), 0);
307
308        let interner = Interner(100);
309        let all_symbols = interner.all_symbols();
310        assert_eq!(all_symbols.count(), 100);
311
312        let interner = Interner(u32::MAX);
313        let all_symbols = interner.all_symbols();
314        assert_eq!(all_symbols.count(), u32::MAX as usize);
315    }
316
317    #[test]
318    fn zero_offset_yielded() {
319        let interner = Interner::default();
320        let mut all_symbols = interner.all_symbols();
321        assert_eq!(all_symbols.next(), None);
322
323        let interner = Interner(5);
324        let mut all_symbols = interner.all_symbols();
325        assert_eq!(all_symbols.next(), Some(Symbol::new(0)));
326        assert_eq!(all_symbols.next(), Some(Symbol::new(1)));
327        assert_eq!(all_symbols.next(), Some(Symbol::new(2)));
328        assert_eq!(all_symbols.next(), Some(Symbol::new(3)));
329        assert_eq!(all_symbols.next(), Some(Symbol::new(4)));
330        assert_eq!(all_symbols.next(), None);
331
332        let interner = Interner(u32::MAX);
333        let mut all_symbols = interner.all_symbols();
334        assert_eq!(all_symbols.next(), Some(Symbol::new(0)));
335        assert_eq!(all_symbols.next_back(), Some(Symbol::new(u32::MAX - 1)));
336    }
337
338    #[test]
339    fn one_offset_count() {
340        let interner = OffByOneInterner::default();
341        let all_symbols = interner.all_symbols();
342        assert_eq!(all_symbols.count(), 0);
343
344        let interner = OffByOneInterner(100);
345        let all_symbols = interner.all_symbols();
346        assert_eq!(all_symbols.count(), 100);
347
348        let interner = OffByOneInterner(u32::MAX);
349        let all_symbols = interner.all_symbols();
350        assert_eq!(all_symbols.count(), (u32::MAX - 1) as usize);
351    }
352
353    #[test]
354    fn one_offset_yielded() {
355        let interner = OffByOneInterner::default();
356        let mut all_symbols = interner.all_symbols();
357        assert_eq!(all_symbols.next(), None);
358
359        let interner = OffByOneInterner(5);
360        let mut all_symbols = interner.all_symbols();
361        assert_eq!(all_symbols.next(), Some(Symbol::new(1)));
362        assert_eq!(all_symbols.next(), Some(Symbol::new(2)));
363        assert_eq!(all_symbols.next(), Some(Symbol::new(3)));
364        assert_eq!(all_symbols.next(), Some(Symbol::new(4)));
365        assert_eq!(all_symbols.next(), Some(Symbol::new(5)));
366        assert_eq!(all_symbols.next(), None);
367
368        let interner = OffByOneInterner(u32::MAX);
369        let mut all_symbols = interner.all_symbols();
370        assert_eq!(all_symbols.next(), Some(Symbol::new(1)));
371        assert_eq!(all_symbols.next_back(), Some(Symbol::new(u32::MAX - 1)));
372    }
373
374    #[test]
375    fn high_offset_count() {
376        let interner = NonZeroInterner::default();
377        let all_symbols = interner.all_symbols();
378        assert_eq!(all_symbols.count(), 0);
379
380        let interner = NonZeroInterner(100);
381        let all_symbols = interner.all_symbols();
382        assert_eq!(all_symbols.count(), 16);
383
384        let interner = NonZeroInterner(u32::MAX);
385        let all_symbols = interner.all_symbols();
386        assert_eq!(all_symbols.count(), 16);
387    }
388
389    #[test]
390    fn high_offset_yielded() {
391        let interner = NonZeroInterner::default();
392        let mut all_symbols = interner.all_symbols();
393        assert_eq!(all_symbols.next(), None);
394
395        let interner = NonZeroInterner(5);
396        let mut all_symbols = interner.all_symbols();
397        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 16)));
398        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 15)));
399        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 14)));
400        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 13)));
401        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 12)));
402        assert_eq!(all_symbols.next(), None);
403
404        let interner = NonZeroInterner(u32::MAX);
405        let mut all_symbols = interner.all_symbols();
406        assert_eq!(all_symbols.next(), Some(Symbol::new(u32::MAX - 16)));
407        assert_eq!(all_symbols.next_back(), Some(Symbol::new(u32::MAX - 1)));
408    }
409}
spinoso_symbol/all_symbols.rs

spinoso_symbol/
all_symbols.rs
