Add split_unfused() to Itertools.

src/lib.rs

@@ -102,6 +102,8 @@ pub mod structs {
     pub use crate::groupbylazy::GroupBy;
     #[cfg(feature = "use_alloc")]
     pub use crate::groupbylazy::{Chunk, ChunkBy, Chunks, Group, Groups, IntoChunks};
+    #[cfg(feature = "use_alloc")]
+    pub use crate::split_unfused::{SplitUnfused};
     #[cfg(feature = "use_std")]
     pub use crate::grouping_map::{GroupingMap, GroupingMapBy};
     pub use crate::intersperse::{Intersperse, IntersperseWith};
@@ -185,6 +187,8 @@ mod format;
 mod group_map;
 #[cfg(feature = "use_alloc")]
 mod groupbylazy;
+#[cfg(feature = "use_alloc")]
+mod split_unfused;
 #[cfg(feature = "use_std")]
 mod grouping_map;
 mod intersperse;
@@ -634,6 +638,50 @@ pub trait Itertools: Iterator {
         self.chunk_by(key)
     }
 
+    /// Split an unfused iterator into a group of iterators.
+    ///
+    /// Given an "unfused iterator"---that is an iterator contains elements
+    /// after `next()` returns `None`---the `split_unfused()` function will
+    /// provide each `None`-terminated sequence as its own iterator. Iterators
+    /// can be dropped and consumed out of order just like
+    /// [`.group_by()`](crate::Itertools::group_by). If consumed in order,
+    /// no memory is allocated.
+    ///
+    /// When the "unfused iterator" returns `None` twice consecutively, it is
+    /// considered exhausted.
+    ///
+    /// ```
+    /// use itertools::Itertools;
+    ///
+    /// // This iterator returns None every third element until it reaches seven.
+    /// struct Frayed(u8);
+    /// impl Iterator for Frayed {
+    ///     type Item = u8;
+    ///     fn next(&mut self) -> Option<u8> {
+    ///         self.0 += 1;
+    ///         (self.0 % 3 != 0 && self.0 <= 7).then_some(self.0)
+    ///     }
+    /// }
+    /// let split = Frayed(0).split_unfused();
+    /// let mut iters = split.into_iter();
+    /// let first = iters.next().unwrap();
+    /// let second = iters.next().unwrap();
+    /// let third = iters.next().unwrap();
+    /// assert!(iters.next().is_none());
+    /// // Iterators can be consumed out of order (but they will then allocate
+    /// // memory).
+    /// assert_eq!(third.collect::<Vec<_>>(), [7]);
+    /// assert_eq!(second.collect::<Vec<_>>(), [4, 5]);
+    /// assert_eq!(first.collect::<Vec<_>>(), [1, 2]);
+    /// ```
+    #[cfg(feature = "use_alloc")]
+    fn split_unfused(self) -> SplitUnfused<Self>
+    where
+        Self: Sized,
+    {
+        split_unfused::new(self)
+    }
+
     /// Return an *iterable* that can chunk the iterator.
     ///
     /// Yield subiterators (chunks) that each yield a fixed number elements,