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 ExactSizeItreator.

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.

In this implementation, I've used `Vec` to store items that will be
reused, and so the method depends on the `use_alloc` feature.

Author: sgtatham

src/array_impl.rs

@@ -0,0 +1,256 @@
+use std::iter::{ExactSizeIterator, FusedIterator};
+
+/// 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,
+    state: CircularArrayWindowsState<I::Item, N>,
+}
+
+#[derive(Debug, Clone)]
+enum CircularArrayWindowsState<T: Clone, const N: usize> {
+    // Simple state enumeration. `NotStarted` allows us to be lazy, by
+    // deferring fetching anything from the input iterator until we're
+    // called on to return our first window. This could almost just be
+    // an `Option<CircularArrayWindowsInner>`, except that we need to
+    // distinguish `Done` from `NotStarted`.
+    NotStarted,
+    Running(CircularArrayWindowsInner<T, N>),
+    Done,
+}
+
+#[derive(Debug, Clone)]
+struct CircularArrayWindowsInner<T: Clone, const N: usize> {
+    // The first N-1 elements read from the iterator are also stored
+    // in `prefix`. `prefix_needed` counts down from N-1 to indicate
+    // how many are yet to be stored.
+    //
+    // When the input iterator runs out, we begin reusing elements
+    // from `prefix`. At this point `cyclepos` changes from None to
+    // Some, and gives the current read position in `prefix`.
+    prefix_needed: usize,
+    prefix: Vec<T>,
+    cyclepos: Option<usize>,
+
+    // During normal use, `ringbuf` contains the N-1 elements of the
+    // previous output window that will be reused in this window. We
+    // read an Nth element and return an array consisting of `ringbuf`
+    // followed by the new element. Then we discard the first element
+    // from `ringbuf` and replace it with the new element.
+    //
+    // As the name suggests, `ringbuf` is physically stored as a ring
+    // buffer. `ringpos` indicates which element is logically first.
+    ringbuf: Vec<T>,
+    ringpos: usize,
+
+    // We want to generate the same number of output windows as the
+    // input iterator had elements. In cases where the input runs out
+    // early and we start recycling `prefix` before we finish writing
+    // it, that's fiddly to keep track of using only the variables
+    // above. So instead `balance` handles knowing when to stop. It is
+    // incremented for every element we read from the input iterator,
+    // and decremented for every window we output.
+    balance: usize,
+}
+
+impl<T: Clone, const N: usize> CircularArrayWindowsInner<T, N> {
+    /// Make an empty `CircularArrayWindowsInner`.
+    fn empty() -> Self {
+        let nm1 = N - 1;
+
+        let mut prefix = Vec::new();
+        let mut ringbuf = Vec::new();
+        prefix.reserve_exact(nm1);
+        ringbuf.reserve_exact(nm1);
+
+        Self {
+            prefix_needed: nm1,
+            prefix,
+            cyclepos: None,
+            ringbuf,
+            ringpos: 0,
+            balance: 0,
+        }
+    }
+
+    /// Return 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).
+    fn get_item(&mut self, iter: &mut impl Iterator<Item = T>) -> T {
+        if let Some(pos) = &mut self.cyclepos {
+            // 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 = (*pos + 1) % self.prefix.len();
+            item
+        } else if let Some(item) = iter.next() {
+            // Read from the input iterator.
+            self.balance += 1;
+            if self.prefix_needed > 0 {
+                // We haven't finished filling `prefix` yet, so push a
+                // clone of the item on to it.
+                self.prefix.push(item.clone());
+                self.prefix_needed -= 1;
+            }
+            item
+        } else {
+            // 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.cyclepos = Some(1 % self.prefix.len());
+            self.prefix[0].clone()
+        }
+    }
+
+    /// Construct an array window to return, given the newly read item
+    /// to go on the end of the output.
+    fn make_window(&mut self, new_item: T) -> [T; N] {
+        let window = std::array::from_fn(|i| {
+            if i + 1 < N {
+                // The first N-1 items come from `ringbuf`
+                self.ringbuf[(i + self.ringpos) % self.ringbuf.len()].clone()
+            } else {
+                // The last item is the new one we just read
+                new_item.clone()
+            }
+        });
+
+        // Replace the oldest item in `ringbuf` with the new one.
+        self.ringbuf[self.ringpos] = new_item;
+        self.ringpos = (self.ringpos + 1) % self.ringbuf.len();
+
+        self.balance -= 1;
+        window
+    }
+}
+
+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]> {
+        if N < 2 {
+            // The generic code doesn't work sensibly when N is too
+            // small, because `ringbuf` and `prefix` have size 0. So
+            // these cases are handled completely separately by this
+            // simpler code, which just consumes an item from the
+            // iterator and returns a window based on just that item.
+            return match &self.state {
+                CircularArrayWindowsState::Done => None,
+                _ => match self.iter.next() {
+                    Some(item) => {
+                        // For N=1 we wrap the item into a singleton
+                        // array. For N=0 we don't even do that – we
+                        // just throw it away and return [].
+                        let mut opt = Some(item);
+                        Some(std::array::from_fn(|_| opt.take().unwrap()))
+                    }
+                    None => {
+                        self.state = CircularArrayWindowsState::Done;
+                        None
+                    }
+                },
+            };
+        }
+        match &mut self.state {
+            // Initialisation code, when next() is called for the first time
+            CircularArrayWindowsState::NotStarted => match self.iter.next() {
+                None => {
+                    // The input iterator was completely empty
+                    self.state = CircularArrayWindowsState::Done;
+                    None
+                }
+                Some(first) => {
+                    // We have at least one item, so we can definitely
+                    // populate `prefix` (even if we have to make N-1
+                    // copies of this element). Set up an `inner`.
+                    let mut inner = CircularArrayWindowsInner::empty();
+
+                    // Call `get_item` even on the first item, using a
+                    // throwaway iterator that just returns the item
+                    // we're already holding. That way `prefix` and
+                    // `balance` are updated the same as they will be
+                    // for future items.
+                    let first = inner.get_item(&mut Some(first).into_iter());
+                    // Put the new item into the ring buffer.
+                    inner.ringbuf.push(first);
+                    for _ in 2..N {
+                        // Now read N-2 further items and fill up the
+                        // rest of `prefix` and `ringbuf`.
+                        let item = inner.get_item(&mut self.iter);
+                        inner.ringbuf.push(item);
+                    }
+
+                    // Now we've read N-1 items, and we're ready to
+                    // read the Nth and return a window.
+                    let last = inner.get_item(&mut self.iter);
+                    let window = inner.make_window(last);
+
+                    self.state = CircularArrayWindowsState::Running(inner);
+
+                    Some(window)
+                }
+            },
+            CircularArrayWindowsState::Running(inner) => {
+                if inner.cyclepos.is_some() && inner.balance == 0 {
+                    // The input iterator has run out, and we've
+                    // emitted as many windows as we read items, so
+                    // we've finished.
+                    self.state = CircularArrayWindowsState::Done;
+                    None
+                } else {
+                    // Normal case. Fetch an item and return a window.
+                    let last = inner.get_item(&mut self.iter);
+                    let window = inner.make_window(last);
+                    Some(window)
+                }
+            }
+            CircularArrayWindowsState::Done => None,
+        }
+    }
+}
+
+// Because `CircularArrayWindowsState::Done` is an absorbing state,
+// this iterator gets fusedness for free.
+impl<I, const N: usize> FusedIterator for CircularArrayWindows<I, N>
+where
+    I: Iterator + Sized,
+    I::Item: Clone,
+{
+}
+
+// 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,
+        state: CircularArrayWindowsState::NotStarted,
+    }
+}

src/lib.rs

@@ -98,6 +98,8 @@ pub mod structs {
         TakeWhileRef, TupleCombinations, Update, WhileSome,
     };
     #[cfg(feature = "use_alloc")]
+    pub use crate::array_impl::CircularArrayWindows;
+    #[cfg(feature = "use_alloc")]
     pub use crate::combinations::{ArrayCombinations, Combinations};
     #[cfg(feature = "use_alloc")]
     pub use crate::combinations_with_replacement::CombinationsWithReplacement;
@@ -174,6 +176,8 @@ pub use crate::unziptuple::{multiunzip, MultiUnzip};
 pub use crate::with_position::Position;
 pub use crate::ziptuple::multizip;
 mod adaptors;
+#[cfg(feature = "use_alloc")]
+mod array_impl;
 mod either_or_both;
 pub use crate::either_or_both::EitherOrBoth;
 #[doc(hidden)]
@@ -900,6 +904,39 @@ 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());
+    /// ```
+    #[cfg(feature = "use_alloc")]
+    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/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::<(_, _)>();

tests/quick.rs

@@ -1300,6 +1300,66 @@ quickcheck! {
     }
 }
 
+// array iterators
+quickcheck! {
+    fn equal_circular_array_windows_0(a: Vec<u8>) -> bool {
+        let x = a.iter().map(|_| [&0u8; 0] );
+        let y = a.iter().circular_array_windows::<0>();
+        assert_eq!(a.len(), y.len());
+        itertools::assert_equal(x,y);
+        true
+    }
+
+    fn equal_circular_array_windows_1(a: Vec<u8>) -> bool {
+        let x = a.iter().map(|e| [e] );
+        let y = a.iter().circular_array_windows::<1>();
+        assert_eq!(a.len(), y.len());
+        itertools::assert_equal(x,y);
+        true
+    }
+
+    fn equal_circular_array_windows_2(a: Vec<u8>) -> bool {
+        let x = (0..a.len()).map(|start_idx| [
+            &a[start_idx],
+            &a[(start_idx + 1) % a.len()],
+        ]);
+        let y = a.iter().circular_array_windows::<2>();
+        assert_eq!(a.len(), y.len());
+        itertools::assert_equal(x,y);
+        true
+    }
+
+    fn equal_circular_array_windows_3(a: Vec<u8>) -> bool {
+        let x = (0..a.len()).map(|start_idx| [
+            &a[start_idx],
+            &a[(start_idx + 1) % a.len()],
+            &a[(start_idx + 2) % a.len()],
+        ]);
+        let y = a.iter().circular_array_windows::<3>();
+        assert_eq!(a.len(), y.len());
+        itertools::assert_equal(x,y);
+        true
+    }
+
+    fn fused_circular_array_windows_is_fused(a: Vec<u8>) -> bool {
+        let mut w0 = a.iter().circular_array_windows::<0>();
+        let mut w1 = a.iter().circular_array_windows::<1>();
+        let mut w2 = a.iter().circular_array_windows::<2>();
+        for _ in 0..a.len() {
+            assert!(w0.next().is_some());
+            assert!(w1.next().is_some());
+            assert!(w2.next().is_some());
+        }
+        assert!(w0.next().is_none());
+        assert!(w1.next().is_none());
+        assert!(w2.next().is_none());
+        assert!(w0.next().is_none());
+        assert!(w1.next().is_none());
+        assert!(w2.next().is_none());
+        true
+    }
+}
+
 // with_position
 quickcheck! {
     fn with_position_exact_size_1(a: Vec<u8>) -> bool {