add array_permutations()

src/lazy_buffer.rs

@@ -1,4 +1,5 @@
 use alloc::vec::Vec;
+use core::array::from_fn;
 use std::iter::Fuse;
 use std::ops::Index;
 
@@ -63,6 +64,13 @@ where
     pub fn get_array<const K: usize>(&self, indices: [usize; K]) -> [I::Item; K] {
         indices.map(|i| self.buffer[i].clone())
     }
+
+    pub fn get_array_from_fn<const K: usize>(
+        &self,
+        mut f: impl FnMut(usize) -> usize,
+    ) -> [I::Item; K] {
+        from_fn(|i| self.buffer[f(i)].clone())
+    }
 }
 
 impl<I, J> Index<J> for LazyBuffer<I>

src/lib.rs

@@ -124,7 +124,7 @@ pub mod structs {
     pub use crate::peek_nth::PeekNth;
     pub use crate::peeking_take_while::PeekingTakeWhile;
     #[cfg(feature = "use_alloc")]
-    pub use crate::permutations::Permutations;
+    pub use crate::permutations::{ArrayPermutations, Permutations};
     #[cfg(feature = "use_alloc")]
     pub use crate::powerset::Powerset;
     pub use crate::process_results_impl::ProcessResults;
@@ -1792,6 +1792,51 @@ pub trait Itertools: Iterator {
         combinations_with_replacement::combinations_with_replacement(self, k)
     }
 
+    /// Return an iterator adaptor that iterates over all `K`-permutations of the
+    /// elements from an iterator.
+    ///
+    /// Iterator element type is `[Self::Item; K]`. The iterator
+    /// produces a new array per iteration, and clones the iterator elements.
+    ///
+    /// If `K` is greater than the length of the input iterator, the resultant
+    /// iterator adaptor will be empty.
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// let perms = (5..8).array_permutations();
+    /// itertools::assert_equal(perms, vec![
+    ///     [5, 6],
+    ///     [5, 7],
+    ///     [6, 5],
+    ///     [6, 7],
+    ///     [7, 5],
+    ///     [7, 6],
+    /// ]);
+    /// ```
+    ///
+    /// Note: Permutations does not take into account the equality of the iterated values.
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// let it = vec![-2, -2].into_iter().array_permutations();
+    /// itertools::assert_equal(it, vec![
+    ///     [-2, -2], // Note: these are the same
+    ///     [-2, -2], // Note: these are the same
+    /// ]);
+    /// ```
+    ///
+    /// Note: The source iterator is collected lazily, and will not be
+    /// re-iterated if the permutations adaptor is completed and re-iterated.
+    #[cfg(feature = "use_alloc")]
+    fn array_permutations<const K: usize>(self) -> ArrayPermutations<Self, K>
+    where
+        Self: Sized,
+        Self::Item: Clone,
+    {
+        permutations::array_permutations(self)
+    }
+
     /// Return an iterator adaptor that iterates over all k-permutations of the
     /// elements from an iterator.
     ///
@@ -1823,10 +1868,10 @@ pub trait Itertools: Iterator {
     /// ```
     /// use itertools::Itertools;
     ///
-    /// let it = vec![2, 2].into_iter().permutations(2);
+    /// let it = vec![-2, -2].into_iter().permutations(2);
     /// itertools::assert_equal(it, vec![
-    ///     vec![2, 2], // Note: these are the same
-    ///     vec![2, 2], // Note: these are the same
+    ///     vec![-2, -2], // Note: these are the same
+    ///     vec![-2, -2], // Note: these are the same
     /// ]);
     /// ```
     ///

src/permutations.rs

@@ -1,29 +1,39 @@
 use alloc::boxed::Box;
 use alloc::vec::Vec;
+use core::marker::PhantomData;
 use std::fmt;
 use std::iter::once;
 use std::iter::FusedIterator;
 
 use super::lazy_buffer::LazyBuffer;
 use crate::size_hint::{self, SizeHint};
 
+/// Iterator for `Vec` valued permutations returned by
+/// [`.permutations()`](crate::Itertools::permutations)
+pub type ArrayPermutations<I, const K: usize> = PermutationsGeneric<I, [<I as Iterator>::Item; K]>;
+/// Iterator for const generic permutations returned by
+/// [`.array_permutations()`](crate::Itertools::array_permutations)
+pub type Permutations<I> = PermutationsGeneric<I, Vec<<I as Iterator>::Item>>;
+
 /// An iterator adaptor that iterates through all the `k`-permutations of the
 /// elements from an iterator.
 ///
-/// See [`.permutations()`](crate::Itertools::permutations) for
+/// See [`.permutations()`](crate::Itertools::permutations) and
+/// [`.array_permutations()`](crate::Itertools::array_permutations) for
 /// more information.
 #[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
-pub struct Permutations<I: Iterator> {
+pub struct PermutationsGeneric<I: Iterator, Item> {
     vals: LazyBuffer<I>,
     state: PermutationState,
+    _item: PhantomData<Item>,
 }
 
-impl<I> Clone for Permutations<I>
+impl<I, Item> Clone for PermutationsGeneric<I, Item>
 where
     I: Clone + Iterator,
     I::Item: Clone,
 {
-    clone_fields!(vals, state);
+    clone_fields!(vals, state, _item);
 }
 
 #[derive(Clone, Debug)]
@@ -41,34 +51,44 @@ enum PermutationState {
     End,
 }
 
-impl<I> fmt::Debug for Permutations<I>
+impl<I, Item> fmt::Debug for PermutationsGeneric<I, Item>
 where
     I: Iterator + fmt::Debug,
     I::Item: fmt::Debug,
 {
     debug_fmt_fields!(Permutations, vals, state);
 }
 
+pub fn array_permutations<I: Iterator, const K: usize>(iter: I) -> ArrayPermutations<I, K> {
+    PermutationsGeneric {
+        vals: LazyBuffer::new(iter),
+        state: PermutationState::Start { k: K },
+        _item: PhantomData,
+    }
+}
+
 pub fn permutations<I: Iterator>(iter: I, k: usize) -> Permutations<I> {
-    Permutations {
+    PermutationsGeneric {
         vals: LazyBuffer::new(iter),
         state: PermutationState::Start { k },
+        _item: PhantomData,
     }
 }
 
-impl<I> Iterator for Permutations<I>
+impl<I, Item> Iterator for PermutationsGeneric<I, Item>
 where
     I: Iterator,
     I::Item: Clone,
+    Item: PermItem<I::Item>,
 {
-    type Item = Vec<I::Item>;
+    type Item = Item;
 
     fn next(&mut self) -> Option<Self::Item> {
-        let Self { vals, state } = self;
+        let Self { vals, state, _item } = self;
         match state {
             PermutationState::Start { k: 0 } => {
                 *state = PermutationState::End;
-                Some(Vec::new())
+                Some(Item::extract_start(vals, 0, 0))
             }
             &mut PermutationState::Start { k } => {
                 vals.prefill(k);
@@ -77,14 +97,11 @@ where
                     return None;
                 }
                 *state = PermutationState::Buffered { k, min_n: k };
-                Some(vals[0..k].to_vec())
+                Some(Item::extract_start(vals, k, k - 1))
             }
             PermutationState::Buffered { ref k, min_n } => {
                 if vals.get_next() {
-                    let item = (0..*k - 1)
-                        .chain(once(*min_n))
-                        .map(|i| vals[i].clone())
-                        .collect();
+                    let item = Item::extract_start(vals, *k, *min_n);
                     *min_n += 1;
                     Some(item)
                 } else {
@@ -99,7 +116,7 @@ where
                             return None;
                         }
                     }
-                    let item = vals.get_at(&indices[0..*k]);
+                    let item = Item::extract_from_prefix(vals, &indices[0..*k]);
                     *state = PermutationState::Loaded { indices, cycles };
                     Some(item)
                 }
@@ -110,14 +127,14 @@ where
                     return None;
                 }
                 let k = cycles.len();
-                Some(vals.get_at(&indices[0..k]))
+                Some(Item::extract_from_prefix(vals, &indices[0..k]))
             }
             PermutationState::End => None,
         }
     }
 
     fn count(self) -> usize {
-        let Self { vals, state } = self;
+        let Self { vals, state, _item } = self;
         let n = vals.count();
         state.size_hint_for(n).1.unwrap()
     }
@@ -130,10 +147,11 @@ where
     }
 }
 
-impl<I> FusedIterator for Permutations<I>
+impl<I, Item> FusedIterator for PermutationsGeneric<I, Item>
 where
     I: Iterator,
     I::Item: Clone,
+    Item: PermItem<I::Item>,
 {
 }
 
@@ -184,3 +202,39 @@ impl PermutationState {
         }
     }
 }
+
+/// A type that can be picked out from a pool or buffer of items from an inner iterator
+/// and in a generic way given their indices.
+pub trait PermItem<T> {
+    fn extract_start<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, len: usize, last: usize) -> Self;
+
+    fn extract_from_prefix<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, indices: &[usize]) -> Self;
+}
+
+impl<T: Clone, const K: usize> PermItem<T> for [T; K] {
+    fn extract_start<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, len: usize, last: usize) -> Self {
+        assert_eq!(len, K);
+        buf.get_array_from_fn(|i| if i + 1 < len { i } else { last })
+    }
+
+    fn extract_from_prefix<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, indices: &[usize]) -> Self {
+        buf.get_array_from_fn(|i| indices[i])
+    }
+}
+
+impl<T: Clone> PermItem<T> for Vec<T> {
+    fn extract_start<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, len: usize, last: usize) -> Self {
+        if len == 0 {
+            Vec::new()
+        } else {
+            (0..len - 1)
+                .chain(once(last))
+                .map(|i| buf[i].clone())
+                .collect()
+        }
+    }
+
+    fn extract_from_prefix<I: Iterator<Item = T>>(buf: &LazyBuffer<I>, indices: &[usize]) -> Self {
+        buf.get_at(indices)
+    }
+}

tests/laziness.rs

@@ -207,6 +207,11 @@ must_use_tests! {
     tuple_combinations3 {
         let _ = Panicking.tuple_combinations::<(_, _, _)>();
     }
+    array_combinations {
+        let _ = Panicking.array_combinations::<0>();
+        let _ = Panicking.array_combinations::<1>();
+        let _ = Panicking.array_combinations::<2>();
+    }
     combinations {
         let _ = Panicking.combinations(0);
         let _ = Panicking.combinations(1);
@@ -217,6 +222,11 @@ must_use_tests! {
         let _ = Panicking.combinations_with_replacement(1);
         let _ = Panicking.combinations_with_replacement(2);
     }
+    array_permutations {
+        let _ = Panicking.array_permutations::<0>();
+        let _ = Panicking.array_permutations::<1>();
+        let _ = Panicking.array_permutations::<2>();
+    }
     permutations {
         let _ = Panicking.permutations(0);
         let _ = Panicking.permutations(1);