Merge #555

555: Add intersperse and intersperse_with free functions r=phimuemue a=zertosh

Aside from automatic parameter conversion using `IntoIterator`, having
`intersperse` and `intersperse_with` as free functions makes it easier for
downstream code to avoid the `unstable_name_collisions` lint because of
lib core's own similarly named `Iterator` methods.
rust-lang/rust#48919

Co-authored-by: Andres Suarez <zertosh@gmail.com>

src/free.rs

@@ -14,8 +14,8 @@ use alloc::{
     string::String,
 };
 
-#[cfg(feature = "use_alloc")]
 use crate::Itertools;
+use crate::intersperse::{Intersperse, IntersperseWith};
 
 pub use crate::adaptors::{
     interleave,
@@ -35,6 +35,41 @@ pub use crate::merge_join::merge_join_by;
 #[cfg(feature = "use_alloc")]
 pub use crate::rciter_impl::rciter;
 
+/// Iterate `iterable` with a particular value inserted between each element.
+///
+/// [`IntoIterator`] enabled version of [`Iterator::intersperse`].
+///
+/// ```
+/// use itertools::intersperse;
+///
+/// itertools::assert_equal(intersperse((0..3), 8), vec![0, 8, 1, 8, 2]);
+/// ```
+pub fn intersperse<I>(iterable: I, element: I::Item) -> Intersperse<I::IntoIter>
+    where I: IntoIterator,
+          <I as IntoIterator>::Item: Clone
+{
+    Itertools::intersperse(iterable.into_iter(), element)
+}
+
+/// Iterate `iterable` with a particular value created by a function inserted
+/// between each element.
+///
+/// [`IntoIterator`] enabled version of [`Iterator::intersperse_with`].
+///
+/// ```
+/// use itertools::intersperse_with;
+///
+/// let mut i = 10;
+/// itertools::assert_equal(intersperse_with((0..3), || { i -= 1; i }), vec![0, 9, 1, 8, 2]);
+/// assert_eq!(i, 8);
+/// ```
+pub fn intersperse_with<I, F>(iterable: I, element: F) -> IntersperseWith<I::IntoIter, F>
+    where I: IntoIterator,
+          F: FnMut() -> I::Item
+{
+    Itertools::intersperse_with(iterable.into_iter(), element)
+}
+
 /// Iterate `iterable` with a running index.
 ///
 /// [`IntoIterator`] enabled version of [`Iterator::enumerate`].

tests/test_core.rs

@@ -9,6 +9,8 @@ use core::iter;
 use itertools as it;
 use crate::it::Itertools;
 use crate::it::interleave;
+use crate::it::intersperse;
+use crate::it::intersperse_with;
 use crate::it::multizip;
 use crate::it::free::put_back;
 use crate::it::iproduct;
@@ -136,6 +138,23 @@ fn test_interleave() {
     it::assert_equal(it, rs.iter());
 }
 
+#[test]
+fn test_intersperse() {
+    let xs = [1u8, 2, 3];
+    let ys = [1u8, 0, 2, 0, 3];
+    let it = intersperse(&xs, &0);
+    it::assert_equal(it, ys.iter());
+}
+
+#[test]
+fn test_intersperse_with() {
+    let xs = [1u8, 2, 3];
+    let ys = [1u8, 10, 2, 10, 3];
+    let i = 10;
+    let it = intersperse_with(&xs, || &i);
+    it::assert_equal(it, ys.iter());
+}
+
 #[allow(deprecated)]
 #[test]
 fn foreach() {