use super::super::TrustedRandomAccess;
use super::super::{Chain, Cloned, Copied, Cycle, Enumerate, Filter, FilterMap, Fuse};
use super::super::{FlatMap, Flatten};
-use super::super::{FromIterator, Intersperse, Product, Sum, Zip};
+use super::super::{FromIterator, Intersperse, IntersperseWith, Product, Sum, Zip};
use super::super::{
Inspect, Map, MapWhile, Peekable, Rev, Scan, Skip, SkipWhile, StepBy, Take, TakeWhile,
};
Zip::new(self, other.into_iter())
}
- /// Places a copy of `separator` between all elements.
+ /// Creates a new iterator which places a copy of `separator` between adjacent
+ /// items of the original iterator.
+ ///
+ /// In case `separator` does not implement [`Clone`] or needs to be
+ /// computed every time, use [`intersperse_with`].
///
/// # Examples
///
/// ```
/// #![feature(iter_intersperse)]
///
- /// let hello = ["Hello", "World"].iter().copied().intersperse(" ").collect::<String>();
- /// assert_eq!(hello, "Hello World");
+ /// let mut a = [0, 1, 2].iter().intersperse(&100);
+ /// assert_eq!(a.next(), Some(&0)); // The first element from `a`.
+ /// assert_eq!(a.next(), Some(&100)); // The separator.
+ /// assert_eq!(a.next(), Some(&1)); // The next element from `a`.
+ /// assert_eq!(a.next(), Some(&100)); // The separator.
+ /// assert_eq!(a.next(), Some(&2)); // The last element from `a`.
+ /// assert_eq!(a.next(), None); // The iterator is finished.
+ /// ```
+ ///
+ /// `intersperse` can be very useful to join an iterator's items using a common element:
/// ```
+ /// #![feature(iter_intersperse)]
+ ///
+ /// let hello = ["Hello", "World", "!"].iter().copied().intersperse(" ").collect::<String>();
+ /// assert_eq!(hello, "Hello World !");
+ /// ```
+ ///
+ /// [`Clone`]: crate::clone::Clone
+ /// [`intersperse_with`]: Iterator::intersperse_with
#[inline]
#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
fn intersperse(self, separator: Self::Item) -> Intersperse<Self>
Intersperse::new(self, separator)
}
+ /// Creates a new iterator which places an item generated by `separator`
+ /// between adjacent items of the original iterator.
+ ///
+ /// The closure will be called exactly once each time an item is placed
+ /// between two adjacent items from the underlying iterator; specifically,
+ /// the closure is not called if the underlying iterator yields less than
+ /// two items and after the last item is yielded.
+ ///
+ /// If the iterator's item implements [`Clone`], it may be easier to use
+ /// [`intersperse`].
+ ///
+ /// # Examples
+ ///
+ /// Basic usage:
+ ///
+ /// ```
+ /// #![feature(iter_intersperse)]
+ ///
+ /// #[derive(PartialEq, Debug)]
+ /// struct NotClone(usize);
+ ///
+ /// let v = vec![NotClone(0), NotClone(1), NotClone(2)];
+ /// let mut it = v.into_iter().intersperse_with(|| NotClone(99));
+ ///
+ /// assert_eq!(it.next(), Some(NotClone(0))); // The first element from `v`.
+ /// assert_eq!(it.next(), Some(NotClone(99))); // The separator.
+ /// assert_eq!(it.next(), Some(NotClone(1))); // The next element from `v`.
+ /// assert_eq!(it.next(), Some(NotClone(99))); // The separator.
+ /// assert_eq!(it.next(), Some(NotClone(2))); // The last element from from `v`.
+ /// assert_eq!(it.next(), None); // The iterator is finished.
+ /// ```
+ ///
+ /// `intersperse_with` can be used in situations where the separator needs
+ /// to be computed:
+ /// ```
+ /// #![feature(iter_intersperse)]
+ ///
+ /// let src = ["Hello", "to", "all", "people", "!!"].iter().copied();
+ ///
+ /// // The closure mutably borrows it's context to generate an item.
+ /// let mut happy_emojis = [" ❤️ ", " 😀 "].iter().copied();
+ /// let separator = || happy_emojis.next().unwrap_or(" 🦀 ");
+ ///
+ /// let result = src.intersperse_with(separator).collect::<String>();
+ /// assert_eq!(result, "Hello ❤️ to 😀 all 🦀 people 🦀 !!");
+ /// ```
+ /// [`Clone`]: crate::clone::Clone
+ /// [`intersperse`]: Iterator::intersperse
+ #[inline]
+ #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")]
+ fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G>
+ where
+ Self: Sized,
+ G: FnMut() -> Self::Item,
+ {
+ IntersperseWith::new(self, separator)
+ }
+
/// Takes a closure and creates an iterator which calls that closure on each
/// element.
///