Add ZipLongest adaptor by Simon Sapin, method is .zip_longest()

ZipLongest originally written by SimonSapin,
and dedicated to itertools rust-lang/rust#19283

Author: root

src/lib.rs

@@ -39,12 +39,14 @@ pub use stride::StrideMut;
 pub use times::Times;
 pub use times::times;
 pub use linspace::{linspace, Linspace};
+pub use zip::{ZipLongest, EitherOrBoth};
 mod adaptors;
 mod intersperse;
 mod linspace;
 mod map;
 mod stride;
 mod times;
+mod zip;
 
 /// A helper trait for (x,y,z) ++ w => (x,y,z,w),
 /// used for implementing `iproduct!` and `izip!`
@@ -243,6 +245,30 @@ pub trait Itertools<A> : Iterator<A> {
         Intersperse::new(self, element)
     }
 
+    /// Creates an iterator which iterates over both this and the specified
+    /// iterators simultaneously, yielding pairs of two optional elements.
+    /// When both iterators return None, all further invocations of next() will
+    /// return None.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use itertools::EitherOrBoth::{Both, Right};
+    /// # use itertools::Itertools;
+    /// let a = [0i];
+    /// let b = [1i, 2i];
+    /// let mut it = a.iter().cloned().zip_longest(b.iter().cloned());
+    /// assert_eq!(it.next(), Some(Both(0, 1)));
+    /// assert_eq!(it.next(), Some(Right(2)));
+    /// assert_eq!(it.next(), None);
+    /// ```
+    ///
+    /// Iterator element type is `EitherOrBoth<A, B>`.
+    #[inline]
+    fn zip_longest<B, U: Iterator<B>>(self, other: U) -> ZipLongest<Self, U> {
+        ZipLongest::new(self, other)
+    }
+
     // non-adaptor methods
 
     /// Consume `n` elements of the iterator eagerly

src/zip.rs

@@ -0,0 +1,106 @@
+use std::cmp;
+use self::EitherOrBoth::{Right, Left, Both};
+
+// ZipLongest originally written by SimonSapin,
+// and dedicated to itertools https://github.com/rust-lang/rust/pull/19283
+
+/// An iterator which iterates two other iterators simultaneously
+#[deriving(Clone)]
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
+pub struct ZipLongest<T, U> {
+    a: T,
+    b: U
+}
+
+impl<T, U> ZipLongest<T, U>
+{
+    /// Create a new ZipLongest iterator.
+    pub fn new(a: T, b: U) -> ZipLongest<T, U>
+    {
+        ZipLongest{a: a, b: b}
+    }
+}
+
+impl<A, B, T: Iterator<A>, U: Iterator<B>> Iterator<EitherOrBoth<A, B>> for ZipLongest<T, U> {
+    #[inline]
+    fn next(&mut self) -> Option<EitherOrBoth<A, B>> {
+        match (self.a.next(), self.b.next()) {
+            (None, None) => None,
+            (Some(a), None) => Some(Left(a)),
+            (None, Some(b)) => Some(Right(b)),
+            (Some(a), Some(b)) => Some(Both(a, b)),
+        }
+    }
+
+    #[inline]
+    fn size_hint(&self) -> (uint, Option<uint>) {
+        let (a_lower, a_upper) = self.a.size_hint();
+        let (b_lower, b_upper) = self.b.size_hint();
+
+        let lower = cmp::max(a_lower, b_lower);
+
+        let upper = match (a_upper, b_upper) {
+            (Some(x), Some(y)) => Some(cmp::max(x,y)),
+            _ => None
+        };
+
+        (lower, upper)
+    }
+}
+
+impl<A, B, T: ExactSizeIterator<A>, U: ExactSizeIterator<B>> DoubleEndedIterator<EitherOrBoth<A, B>>
+for ZipLongest<T, U> {
+    #[inline]
+    fn next_back(&mut self) -> Option<EitherOrBoth<A, B>> {
+        use std::cmp::{Equal, Greater, Less};
+        match self.a.len().cmp(&self.b.len()) {
+            Equal => match (self.a.next_back(), self.b.next_back()) {
+                (None, None) => None,
+                (Some(a), Some(b)) => Some(Both(a, b)),
+                // These can only happen if .len() is inconsistent with .next_back()
+                (Some(a), None) => Some(Left(a)),
+                (None, Some(b)) => Some(Right(b)),
+            },
+            Greater => self.a.next_back().map(Left),
+            Less => self.b.next_back().map(Right),
+        }
+    }
+}
+
+impl<A, B, T: RandomAccessIterator<A>, U: RandomAccessIterator<B>>
+RandomAccessIterator<EitherOrBoth<A, B>> for ZipLongest<T, U> {
+    #[inline]
+    fn indexable(&self) -> uint {
+        cmp::max(self.a.indexable(), self.b.indexable())
+    }
+
+    #[inline]
+    fn idx(&mut self, index: uint) -> Option<EitherOrBoth<A, B>> {
+        match (self.a.idx(index), self.b.idx(index)) {
+            (None, None) => None,
+            (Some(a), None) => Some(Left(a)),
+            (None, Some(b)) => Some(Right(b)),
+            (Some(a), Some(b)) => Some(Both(a, b)),
+        }
+    }
+}
+
+#[unstable = "trait is unstable"]
+impl<A, B, T, U> ExactSizeIterator<EitherOrBoth<A, B>> for ZipLongest<T, U>
+    where T: ExactSizeIterator<A>, U: ExactSizeIterator<B> {}
+
+
+/// A value yielded by `ZipLongest`.
+/// Contains one or two values,
+/// depending on which of the input iterators are exhausted.
+#[deriving(Clone, PartialEq, Eq, Show)]
+pub enum EitherOrBoth<A, B> {
+    /// Neither input iterator is exhausted yet, yielding two values.
+    Both(A, B),
+    /// The parameter iterator of `.zip_longest()` is exhausted,
+    /// only yielding a value from the `self` iterator.
+    Left(A),
+    /// The `self` iterator of `.zip_longest()` is exhausted,
+    /// only yielding a value from the parameter iterator.
+    Right(B),
+}