New method circular_array_windows().

This is very like the existing `circular_tuple_windows`, but imposes
the minimum possible bounds on the input iterator: it must have
cloneable items because each item is returned N times, and it must be
Sized so that it can be stored in a struct. Unlike
`circular_tuple_windows`, it doesn't require the input iterator itself
to have extra traits, like Clone or ExactSizeIterator.

Because the return type is an array (as suggested in #1084), we must
handle the zero-length case, because you can't have a constraint
`N>0`. In that situation we still read to the end of the input
iterator, discard each item as we read it, and return a zero-length
array per item, preserving the invariant that this iterator is the
same length as the input one.

Author: sgtatham

src/array_impl.rs

@@ -0,0 +1,158 @@
+use std::iter::ExactSizeIterator;
+
+/// An iterator over all windows, wrapping back to the first elements when the
+/// window would otherwise exceed the length of the iterator, producing arrays
+/// of a specific size.
+///
+/// See [`.circular_array_windows()`](crate::Itertools::circular_array_windows)
+/// for more information.
+#[derive(Debug, Clone)]
+pub struct CircularArrayWindows<I, const N: usize>
+where
+    I: Iterator + Sized,
+    I::Item: Clone,
+{
+    iter: I,
+    inner: Option<CircularArrayWindowsInner<I::Item, N>>,
+}
+
+#[derive(Debug, Clone)]
+struct CircularArrayWindowsInner<T: Clone, const N: usize> {
+    prefix: [T; N],
+    prefix_pos: Option<usize>,
+    ringbuf: [T; N],
+    ringpos: usize,
+}
+
+impl<T: Clone, const N: usize> CircularArrayWindowsInner<T, N> {
+    fn new(first: T, iter: &mut impl Iterator<Item = T>) -> Self {
+        let mut items = std::array::from_fn(|_| None);
+        let mut prefix_pos = None;
+        if N > 0 {
+            items[0] = Some(first);
+        }
+        for i in 1..N {
+            let item = iter.next();
+            if item.is_none() {
+                for j in i..N {
+                    items[j] = items[j - i].clone();
+                }
+                prefix_pos = Some(N - i);
+                break;
+            }
+            items[i] = item;
+        }
+        let items = items.map(Option::unwrap);
+        Self {
+            prefix: items.clone(),
+            prefix_pos,
+            ringbuf: items,
+            ringpos: 0,
+        }
+    }
+
+    /// Read the next item in the logical input sequence (consisting
+    /// of the contents of the input iterator followed by N-1 items
+    /// recycling from the beginning). Add it to the ring buffer.
+    fn read_item(&mut self, iter: &mut impl Iterator<Item = T>) -> bool {
+        let item = if let Some(pos) = &mut self.prefix_pos {
+            // The input iterator has already run out, so clone an
+            // element from `prefix`, wrapping round to the start as
+            // necessary.
+            let item = self.prefix[*pos].clone();
+            *pos += 1;
+            item
+        } else if let Some(item) = iter.next() {
+            // Read from the input iterator.
+            item
+        } else if N > 1 {
+            // The input iterator has run out right now, so clone the
+            // first element of `prefix`, and set cyclepos to point to
+            // the next one.
+            self.prefix_pos = Some(1);
+            self.prefix[0].clone()
+        } else {
+            // Special case if N=1: don't read an item at all if the
+            // input iterator has run out.
+            self.prefix_pos = Some(0);
+            return false;
+        };
+
+        if N > 0 {
+            self.ringbuf[self.ringpos] = item;
+            self.ringpos = (self.ringpos + 1) % N;
+        }
+        true
+    }
+
+    /// Construct an array window to return, given the newly read item
+    /// to go on the end of the output.
+    fn make_window(&mut self) -> [T; N] {
+        std::array::from_fn(|i| self.ringbuf[(i + self.ringpos) % N].clone())
+    }
+}
+
+impl<I, const N: usize> Iterator for CircularArrayWindows<I, N>
+where
+    I: Iterator + Sized,
+    I::Item: Clone,
+{
+    type Item = [I::Item; N];
+
+    fn next(&mut self) -> Option<[I::Item; N]> {
+        match &mut self.inner {
+            // Initialisation code, when next() is called for the first time
+            None => match self.iter.next() {
+                None => {
+                    // The input iterator was completely empty
+                    None
+                }
+                Some(first) => {
+                    // We have at least one item, so we can definitely
+                    // populate `prefix` (even if we have to make N
+                    // copies of this element).
+
+                    let mut inner = CircularArrayWindowsInner::new(first, &mut self.iter);
+                    let window = inner.make_window();
+                    self.inner = Some(inner);
+                    Some(window)
+                }
+            },
+            Some(inner) => {
+                if inner.prefix_pos.is_some_and(|pos| pos + 1 >= N) {
+                    // The input iterator has run out, and we've
+                    // emitted as many windows as we read items, so
+                    // we've finished.
+                    None
+                } else {
+                    // Normal case. Fetch an item and return a window.
+                    if inner.read_item(&mut self.iter) {
+                        Some(inner.make_window())
+                    } else {
+                        None
+                    }
+                }
+            }
+        }
+    }
+}
+
+// We return exactly one window per input item, so if the input
+// iterator knows its length, then so do we.
+impl<I, const N: usize> ExactSizeIterator for CircularArrayWindows<I, N>
+where
+    I: Iterator + Sized + ExactSizeIterator,
+    I::Item: Clone,
+{
+    fn len(&self) -> usize {
+        self.iter.len()
+    }
+}
+
+pub fn circular_array_windows<I, const N: usize>(iter: I) -> CircularArrayWindows<I, N>
+where
+    I: Iterator + Sized,
+    I::Item: Clone,
+{
+    CircularArrayWindows { iter, inner: None }
+}

src/lib.rs

@@ -97,6 +97,7 @@ pub mod structs {
         FilterOk, Interleave, InterleaveShortest, MapInto, MapOk, Positions, Product, PutBack,
         TakeWhileRef, TupleCombinations, Update, WhileSome,
     };
+    pub use crate::array_impl::CircularArrayWindows;
     #[cfg(feature = "use_alloc")]
     pub use crate::combinations::{ArrayCombinations, Combinations};
     #[cfg(feature = "use_alloc")]
@@ -174,6 +175,7 @@ pub use crate::unziptuple::{multiunzip, MultiUnzip};
 pub use crate::with_position::Position;
 pub use crate::ziptuple::multizip;
 mod adaptors;
+mod array_impl;
 mod either_or_both;
 pub use crate::either_or_both::EitherOrBoth;
 #[doc(hidden)]
@@ -900,6 +902,38 @@ pub trait Itertools: Iterator {
         tuple_impl::tuples(self)
     }
 
+    /// Return an iterator over all windows, wrapping back to the first
+    /// elements when the window would otherwise exceed the length of the
+    /// iterator, producing arrays of size `N`.
+    ///
+    /// `circular_array_windows` clones the iterator elements so that
+    /// they can be part of successive windows, this makes it most
+    /// suited for iterators of references and other values that are
+    /// cheap to copy.
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    /// let mut v = Vec::new();
+    /// for [a, b] in (1..5).circular_array_windows() {
+    ///     v.push([a, b]);
+    /// }
+    /// assert_eq!(v, vec![[1, 2], [2, 3], [3, 4], [4, 1]]);
+    ///
+    /// let mut it = (1..5).circular_array_windows();
+    /// assert_eq!(Some([1, 2, 3]), it.next());
+    /// assert_eq!(Some([2, 3, 4]), it.next());
+    /// assert_eq!(Some([3, 4, 1]), it.next());
+    /// assert_eq!(Some([4, 1, 2]), it.next());
+    /// assert_eq!(None, it.next());
+    /// ```
+    fn circular_array_windows<const N: usize>(self) -> CircularArrayWindows<Self, N>
+    where
+        Self: Sized,
+        Self::Item: Clone,
+    {
+        array_impl::circular_array_windows(self)
+    }
+
     /// Split into an iterator pair that both yield all elements from
     /// the original iterator.
     ///

tests/arrays.rs

@@ -0,0 +1,156 @@
+use itertools::Itertools;
+
+#[test]
+fn circular_array_windows() {
+    let [vec0, vec1, vec2, vec4, vec10] = [
+        vec![],
+        vec![1],
+        vec![1, 2],
+        vec![1, 2, 3, 4],
+        vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    ];
+
+    assert_eq!(
+        vec10
+            .iter()
+            .copied()
+            .circular_array_windows::<2>()
+            .collect::<Vec<_>>(),
+        vec![
+            [1, 2],
+            [2, 3],
+            [3, 4],
+            [4, 5],
+            [5, 6],
+            [6, 7],
+            [7, 8],
+            [8, 9],
+            [9, 10],
+            [10, 1]
+        ]
+    );
+
+    assert_eq!(
+        vec4.iter()
+            .copied()
+            .circular_array_windows::<2>()
+            .collect::<Vec<_>>(),
+        vec![[1, 2], [2, 3], [3, 4], [4, 1]]
+    );
+
+    assert_eq!(
+        vec2.iter()
+            .copied()
+            .circular_array_windows::<2>()
+            .collect::<Vec<_>>(),
+        vec![[1, 2], [2, 1]]
+    );
+
+    assert_eq!(
+        vec1.iter()
+            .copied()
+            .circular_array_windows::<2>()
+            .collect::<Vec<_>>(),
+        vec![[1, 1]]
+    );
+
+    assert_eq!(
+        vec0.iter()
+            .copied()
+            .circular_array_windows::<2>()
+            .collect::<Vec<_>>(),
+        Vec::<[i32; 2]>::new()
+    );
+
+    assert_eq!(
+        vec10
+            .iter()
+            .copied()
+            .circular_array_windows::<4>()
+            .collect::<Vec<_>>(),
+        vec![
+            [1, 2, 3, 4],
+            [2, 3, 4, 5],
+            [3, 4, 5, 6],
+            [4, 5, 6, 7],
+            [5, 6, 7, 8],
+            [6, 7, 8, 9],
+            [7, 8, 9, 10],
+            [8, 9, 10, 1],
+            [9, 10, 1, 2],
+            [10, 1, 2, 3],
+        ]
+    );
+
+    assert_eq!(
+        vec0.iter()
+            .copied()
+            .circular_array_windows::<0>()
+            .collect::<Vec<_>>(),
+        Vec::<[i32; 0]>::new()
+    );
+
+    assert_eq!(
+        vec1.iter()
+            .copied()
+            .circular_array_windows::<0>()
+            .collect::<Vec<_>>(),
+        vec![[]]
+    );
+
+    assert_eq!(
+        vec2.iter()
+            .copied()
+            .circular_array_windows::<0>()
+            .collect::<Vec<_>>(),
+        vec![[], []]
+    );
+
+    assert_eq!(
+        vec0.iter()
+            .copied()
+            .circular_array_windows::<1>()
+            .collect::<Vec<_>>(),
+        Vec::<[i32; 1]>::new()
+    );
+
+    assert_eq!(
+        vec1.iter()
+            .copied()
+            .circular_array_windows::<1>()
+            .collect::<Vec<_>>(),
+        vec![[1]]
+    );
+
+    assert_eq!(
+        vec2.iter()
+            .copied()
+            .circular_array_windows::<1>()
+            .collect::<Vec<_>>(),
+        vec![[1], [2]]
+    );
+
+    assert_eq!(
+        vec1.iter()
+            .copied()
+            .circular_array_windows::<7>()
+            .collect::<Vec<_>>(),
+        vec![[1, 1, 1, 1, 1, 1, 1]]
+    );
+
+    assert_eq!(
+        vec2.iter()
+            .copied()
+            .circular_array_windows::<7>()
+            .collect::<Vec<_>>(),
+        vec![[1, 2, 1, 2, 1, 2, 1], [2, 1, 2, 1, 2, 1, 2]]
+    );
+
+    assert_eq!(
+        vec4.iter()
+            .copied()
+            .circular_array_windows::<7>()
+            .collect::<Vec<_>>(),
+        vec![[1, 2, 1, 2, 1, 2, 1], [2, 1, 2, 1, 2, 1, 2]]
+    );
+}

tests/laziness.rs

@@ -104,6 +104,12 @@ must_use_tests! {
         let _ = Panicking.circular_tuple_windows::<(_, _)>();
         let _ = Panicking.circular_tuple_windows::<(_, _, _)>();
     }
+    circular_array_windows {
+        let _ = Panicking.circular_array_windows::<0>();
+        let _ = Panicking.circular_array_windows::<1>();
+        let _ = Panicking.circular_array_windows::<2>();
+        let _ = Panicking.circular_array_windows::<3>();
+    }
     tuples {
         let _ = Panicking.tuples::<(_,)>();
         let _ = Panicking.tuples::<(_, _)>();