Add itertools::generate

It's an easier to use alternative to unfoled,
modeled after Kotlin's generateSequence.

Author: matklad

src/lib.rs

@@ -91,7 +91,7 @@ pub mod structs {
     #[cfg(feature = "use_std")]
     pub use rciter_impl::RcIter;
     pub use repeatn::RepeatN;
-    pub use sources::{RepeatCall, Unfold, Iterate};
+    pub use sources::{RepeatCall, Generate, Unfold, Iterate};
     #[cfg(feature = "use_std")]
     pub use tee::Tee;
     pub use tuple_impl::{TupleBuffer, TupleWindows, Tuples};
@@ -114,7 +114,7 @@ pub use minmax::MinMaxResult;
 pub use peeking_take_while::PeekingNext;
 pub use process_results_impl::process_results;
 pub use repeatn::repeat_n;
-pub use sources::{repeat_call, unfold, iterate};
+pub use sources::{repeat_call, generate, unfold, iterate};
 pub use with_position::Position;
 pub use ziptuple::multizip;
 mod adaptors;
@@ -1888,13 +1888,13 @@ pub trait Itertools : Iterator {
 
     /// Return a `HashMap` of keys mapped to `Vec`s of values. Keys and values
     /// are taken from `(Key, Value)` tuple pairs yielded by the input iterator.
-    /// 
+    ///
     /// ```
     /// use itertools::Itertools;
-    /// 
+    ///
     /// let data = vec![(0, 10), (2, 12), (3, 13), (0, 20), (3, 33), (2, 42)];
     /// let lookup = data.into_iter().into_group_map();
-    /// 
+    ///
     /// assert_eq!(lookup[&0], vec![10, 20]);
     /// assert_eq!(lookup.get(&1), None);
     /// assert_eq!(lookup[&2], vec![12, 42]);

src/sources.rs

@@ -135,6 +135,71 @@ impl<A, St, F> Iterator for Unfold<St, F>
     }
 }
 
+/// Returns an iterator that starts with the `seed` and repeatedly
+/// calls the `step` function to produce the next value. Iterator
+/// stops as soon as `None` is encountered
+///
+/// ```
+/// // an iterator that yields Collatz sequence.
+/// // https://en.wikipedia.org/wiki/Collatz_conjecture
+///
+/// use itertools::generate;
+///
+/// let collatz = generate(Some(12), |&n| {
+///     if n == 1 {
+///         None
+///     } else if n % 2 == 0 {
+///         Some(n / 2)
+///     } else {
+///         Some(3 * n + 1)
+///     }
+/// });
+///
+/// itertools::assert_equal(collatz,
+///                         vec![12, 6, 3, 10, 5, 16, 8, 4, 2, 1]);
+/// ```
+pub fn generate<T, F>(seed: Option<T>, step: F) -> Generate<T, F>
+    where F: FnMut(&T) -> Option<T>
+{
+    Generate {
+        next: seed,
+        step: step,
+    }
+}
+
+impl<T, F> fmt::Debug for Generate<T, F>
+    where T: fmt::Debug,
+{
+    debug_fmt_fields!(Genrate, next);
+}
+
+/// See [`unfold`](../fn.generate.html) for more information.
+#[derive(Clone)]
+#[must_use = "iterators are lazy and do nothing unless consumed"]
+pub struct Generate<T, F> {
+    next: Option<T>,
+    step: F,
+}
+
+impl<T, F> Iterator for Generate<T, F>
+    where F: FnMut(&T) -> Option<T>
+{
+    type Item = T;
+
+    #[inline]
+    fn next(&mut self) -> Option<T> {
+        self.next.take().map(|next| {
+            self.next = (self.step)(&next);
+            next
+        })
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (usize, Option<usize>) {
+        (self.next.is_some() as usize, None)
+    }
+}
+
 /// An iterator that infinitely applies function to value and yields results.
 ///
 /// This `struct` is created by the [`iterate()`] function. See its documentation for more.