Skip to main content

astrs_data/array/
iter.rs

1//! The shared null-aware iterator every array family reuses.
2//!
3//! Eleven array types need the same iterator: yield `Option<T>`, `None` for a
4//! null slot, exact size, double-ended. Rather than write it eleven times,
5//! each array implements [`ArrayAccessor`] on its *reference* type — which is
6//! what lets `StringArray` yield `&'a str` without copying — and gets
7//! [`ArrayIter`] for free.
8//!
9//! ```
10//! use astrs_data::array::{Array, StringArray};
11//!
12//! let names = StringArray::from_opt_iter([Some("lidar"), None, Some("imu")]);
13//! let collected: Vec<Option<&str>> = names.iter().collect();
14//! assert_eq!(collected, vec![Some("lidar"), None, Some("imu")]);
15//! assert_eq!(names.iter().rev().flatten().collect::<Vec<_>>(), vec!["imu", "lidar"]);
16//! ```
17
18/// Random access to an array's logical values, null-aware.
19///
20/// Implemented on `&'a ConcreteArray` rather than on `ConcreteArray` so that
21/// borrowing value types (`&str`, `&[u8]`, [`crate::ArrayRef`]) can be
22/// returned without a copy.
23pub trait ArrayAccessor {
24    /// The logical value type, e.g. `i32`, `&'a str` or `&'a [u8]`.
25    type Item;
26
27    /// Number of logical slots.
28    fn accessor_len(&self) -> usize;
29
30    /// The value at `index`, or `None` when the slot is null or out of range.
31    fn accessor_get(&self, index: usize) -> Option<Self::Item>;
32}
33
34/// Double-ended, exact-size iterator over an array's logical values.
35///
36/// Yields `None` for null slots, so the item type is `Option<A::Item>`.
37#[derive(Debug, Clone)]
38pub struct ArrayIter<A: ArrayAccessor> {
39    /// The borrowed array.
40    array: A,
41    /// Next index from the front.
42    front: usize,
43    /// One past the next index from the back.
44    back: usize,
45}
46
47impl<A: ArrayAccessor> ArrayIter<A> {
48    /// Starts an iteration over the whole array.
49    #[must_use]
50    pub fn new(array: A) -> Self {
51        let back = array.accessor_len();
52        Self {
53            array,
54            front: 0,
55            back,
56        }
57    }
58}
59
60impl<A: ArrayAccessor> Iterator for ArrayIter<A> {
61    type Item = Option<A::Item>;
62
63    #[inline]
64    fn next(&mut self) -> Option<Self::Item> {
65        if self.front >= self.back {
66            return None;
67        }
68        let value = self.array.accessor_get(self.front);
69        self.front += 1;
70        Some(value)
71    }
72
73    #[inline]
74    fn size_hint(&self) -> (usize, Option<usize>) {
75        let remaining = self.back - self.front;
76        (remaining, Some(remaining))
77    }
78
79    #[inline]
80    fn count(self) -> usize {
81        self.back - self.front
82    }
83
84    #[inline]
85    fn nth(&mut self, n: usize) -> Option<Self::Item> {
86        self.front = self.front.saturating_add(n);
87        self.next()
88    }
89}
90
91impl<A: ArrayAccessor> DoubleEndedIterator for ArrayIter<A> {
92    #[inline]
93    fn next_back(&mut self) -> Option<Self::Item> {
94        if self.front >= self.back {
95            return None;
96        }
97        self.back -= 1;
98        Some(self.array.accessor_get(self.back))
99    }
100}
101
102impl<A: ArrayAccessor> ExactSizeIterator for ArrayIter<A> {}
103
104impl<A: ArrayAccessor> std::iter::FusedIterator for ArrayIter<A> {}
105
106#[cfg(test)]
107mod tests {
108    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
109
110    use crate::array::{Int32Array, StringArray};
111
112    #[test]
113    fn iterates_forwards_and_backwards() {
114        let values = Int32Array::from_opt_iter([Some(1), None, Some(3), Some(4)]);
115        let mut iter = values.iter();
116        assert_eq!(iter.len(), 4);
117        assert_eq!(iter.next(), Some(Some(1)));
118        assert_eq!(iter.next_back(), Some(Some(4)));
119        assert_eq!(iter.len(), 2);
120        assert_eq!(iter.collect::<Vec<_>>(), vec![None, Some(3)]);
121    }
122
123    #[test]
124    fn exhausted_iterators_stay_exhausted() {
125        let values = Int32Array::from_values([1]);
126        let mut iter = values.iter();
127        assert_eq!(iter.next(), Some(Some(1)));
128        assert_eq!(iter.next(), None);
129        assert_eq!(iter.next(), None);
130        assert_eq!(iter.next_back(), None);
131    }
132
133    #[test]
134    fn empty_array_iterates_zero_times() {
135        let values = Int32Array::from_values([] as [i32; 0]);
136        assert_eq!(values.iter().count(), 0);
137        assert_eq!(values.iter().len(), 0);
138        assert_eq!(values.iter().next(), None);
139    }
140
141    #[test]
142    fn nth_skips() {
143        let values = Int32Array::from_values([0, 1, 2, 3, 4]);
144        let mut iter = values.iter();
145        assert_eq!(iter.nth(2), Some(Some(2)));
146        assert_eq!(iter.next(), Some(Some(3)));
147        assert_eq!(iter.nth(99), None);
148    }
149
150    #[test]
151    fn borrowing_items_keep_the_array_lifetime() {
152        let names = StringArray::from_opt_iter([Some("a"), None, Some("ccc")]);
153        let lengths: Vec<Option<usize>> = names.iter().map(|s| s.map(str::len)).collect();
154        assert_eq!(lengths, vec![Some(1), None, Some(3)]);
155        assert_eq!(names.iter().flatten().count(), 2);
156    }
157
158    #[test]
159    fn count_short_circuits() {
160        let values = Int32Array::from_values([1, 2, 3]);
161        assert_eq!(values.iter().count(), 3);
162        let mut iter = values.iter();
163        let _ = iter.next();
164        assert_eq!(iter.count(), 2);
165    }
166}