.

src/extensions/sequence.rs

@@ -575,6 +575,29 @@ pub trait Sequence<Item> {
     self.into_iter().zip(elements).flat_map(|(item1, item2)| iter::once(item1).chain(iter::once(item2))).collect()
   }
 
+  /// Creates a new sequence which places a copy of `separator` between adjacent
+  /// items of the original sequence.
+  ///
+  /// In case `separator` does not implement [`Clone`] or needs to be
+  /// computed every time, use [`intersperse_with`].
+  ///
+  /// [`intersperse_with`]: Sequence::intersperse_with
+  ///
+  /// # Examples
+  ///
+  /// ```
+  /// use cantrip::*;
+  ///
+  /// # let source = vec![1, 2, 3];
+  /// let a = vec![1, 2, 3];
+  ///
+  /// // assert_eq!(a.intersperse_with(1, 0), vec![1, 0, 2, 0, 3]);
+  /// # let a = source.clone();
+  /// // assert_eq!(a.intersperse_with(2, 0), vec![1, 2, 0, 3]);
+  ///
+  /// # let a = source.clone();
+  /// // assert_eq!(a.intersperse_with(3, 0), vec![1, 2, 3]);
+  /// ```
   #[inline]
   fn intersperse(self, interval: usize, value: Item) -> Self
   where
@@ -584,6 +607,30 @@ pub trait Sequence<Item> {
     self.intersperse_with(interval, || value.clone())
   }
 
+  // FIXME - fix failing test case
+  /// Creates a new sequence which places an item generated by `separator`
+  /// between adjacent items of this sequence.
+  ///
+  /// The closure will be called exactly once each time an item is placed
+  /// between two adjacent items from the underlying sequence.
+  /// The closure is not called if the underlying sequence yields less than
+  /// two items and after the last item is yielded.
+  ///
+  /// # Example
+  ///
+  /// ```
+  /// use cantrip::*;
+  ///
+  /// # let source = vec![1, 2, 3];
+  /// let a = vec![1, 2, 3];
+  ///
+  /// // assert_eq!(a.intersperse_with(1, || 0), vec![1, 0, 2, 0, 3]);
+  /// # let a = source.clone();
+  /// // assert_eq!(a.intersperse_with(2, || 0), vec![1, 2, 0, 3]);
+  ///
+  /// # let a = source.clone();
+  /// // assert_eq!(a.intersperse_with(3, || 0), vec![1, 2, 3]);
+  /// ```
   fn intersperse_with(self, interval: usize, mut to_value: impl FnMut() -> Item) -> Self
   where
     Item: Clone,