[COLLECTIONS-795] Add a new Iterator to allowing zipping over two iterators of different types

pom.xml

@@ -461,6 +461,9 @@
     <contributor>
       <name>Arturo Bernal</name>
     </contributor>
+    <contributor>
+      <name>Anant Damle</name>
+    </contributor>
   </contributors>
 
   <dependencies>

src/main/java/org/apache/commons/collections4/IterableUtils.java

@@ -27,6 +27,7 @@
 
 import org.apache.commons.collections4.functors.EqualPredicate;
 import org.apache.commons.collections4.iterators.LazyIteratorChain;
+import org.apache.commons.collections4.iterators.PairedIterator.PairedItem;
 import org.apache.commons.collections4.iterators.ReverseListIterator;
 import org.apache.commons.collections4.iterators.UniqueFilterIterator;
 
@@ -518,6 +519,40 @@ public Iterator<E> iterator() {
         };
     }
 
+    /**
+     * Provides iteration over the elements contained in a pair of Iterables in-tandem.
+     * <p>
+     * The returned iterable has an iterator that traverses the elements in {@code a}
+     * and {@code b} together until one of the iterables is traversed completely.
+     * </p>
+     *
+     * <p>
+     * The returned iterable's iterator does NOT support {@code remove()}.
+     * </p>
+     *
+     * @param <L> the left elements' type
+     * @param <R> the right elements' type
+     * @param left the iterable for the left side elements
+     * @param right the iterable for the right side elements
+     * @return an iterable, over the decorated iterables to traverse them together until one is
+     * exhausted
+     * @throws NullPointerException if any iterator is null
+     * @since 4.5
+     */
+    public static <L, R> Iterable<PairedItem<L, R>> pairedIterable(final Iterable<L> left, final Iterable<R> right) {
+        checkNotNull(left);
+        checkNotNull(right);
+
+        return new FluentIterable<PairedItem<L, R>>(){
+            @Override
+            public Iterator<PairedItem<L, R>> iterator() {
+                return IteratorUtils.pairedIterator(left.iterator(), right.iterator());
+            }
+        };
+    }
+
+    // Utility methods
+    // ----------------------------------------------------------------------
     /**
      * Returns an immutable empty iterable if the argument is null,
      * or the argument itself otherwise.

src/main/java/org/apache/commons/collections4/IteratorUtils.java

@@ -16,55 +16,15 @@
  */
 package org.apache.commons.collections4;
 
-import java.lang.reflect.Array;
-import java.lang.reflect.Method;
-import java.util.ArrayList;
-import java.util.Collection;
-import java.util.Comparator;
-import java.util.Dictionary;
-import java.util.Enumeration;
-import java.util.Iterator;
-import java.util.List;
-import java.util.ListIterator;
-import java.util.Map;
-import java.util.Objects;
-
 import org.apache.commons.collections4.functors.EqualPredicate;
-import org.apache.commons.collections4.iterators.ArrayIterator;
-import org.apache.commons.collections4.iterators.ArrayListIterator;
-import org.apache.commons.collections4.iterators.BoundedIterator;
-import org.apache.commons.collections4.iterators.CollatingIterator;
-import org.apache.commons.collections4.iterators.EmptyIterator;
-import org.apache.commons.collections4.iterators.EmptyListIterator;
-import org.apache.commons.collections4.iterators.EmptyMapIterator;
-import org.apache.commons.collections4.iterators.EmptyOrderedIterator;
-import org.apache.commons.collections4.iterators.EmptyOrderedMapIterator;
-import org.apache.commons.collections4.iterators.EnumerationIterator;
-import org.apache.commons.collections4.iterators.FilterIterator;
-import org.apache.commons.collections4.iterators.FilterListIterator;
-import org.apache.commons.collections4.iterators.IteratorChain;
-import org.apache.commons.collections4.iterators.IteratorEnumeration;
-import org.apache.commons.collections4.iterators.IteratorIterable;
-import org.apache.commons.collections4.iterators.ListIteratorWrapper;
-import org.apache.commons.collections4.iterators.LoopingIterator;
-import org.apache.commons.collections4.iterators.LoopingListIterator;
-import org.apache.commons.collections4.iterators.NodeListIterator;
-import org.apache.commons.collections4.iterators.ObjectArrayIterator;
-import org.apache.commons.collections4.iterators.ObjectArrayListIterator;
-import org.apache.commons.collections4.iterators.ObjectGraphIterator;
-import org.apache.commons.collections4.iterators.PeekingIterator;
-import org.apache.commons.collections4.iterators.PushbackIterator;
-import org.apache.commons.collections4.iterators.SingletonIterator;
-import org.apache.commons.collections4.iterators.SingletonListIterator;
-import org.apache.commons.collections4.iterators.SkippingIterator;
-import org.apache.commons.collections4.iterators.TransformIterator;
-import org.apache.commons.collections4.iterators.UnmodifiableIterator;
-import org.apache.commons.collections4.iterators.UnmodifiableListIterator;
-import org.apache.commons.collections4.iterators.UnmodifiableMapIterator;
-import org.apache.commons.collections4.iterators.ZippingIterator;
+import org.apache.commons.collections4.iterators.*;
 import org.w3c.dom.Node;
 import org.w3c.dom.NodeList;
 
+import java.lang.reflect.Array;
+import java.lang.reflect.Method;
+import java.util.*;
+
 /**
  * Provides static utility methods and decorators for {@link Iterator}
  * instances. The implementations are provided in the iterators subpackage.
@@ -138,7 +98,7 @@ public static <E> ResettableIterator<E> emptyIterator() {
      * @return a list iterator over nothing
      */
     public static <E> ResettableListIterator<E> emptyListIterator() {
-        return EmptyListIterator.<E>resettableEmptyListIterator();
+        return EmptyListIterator.resettableEmptyListIterator();
     }
 
     /**
@@ -151,7 +111,7 @@ public static <E> ResettableListIterator<E> emptyListIterator() {
      * @return an ordered iterator over nothing
      */
     public static <E> OrderedIterator<E> emptyOrderedIterator() {
-        return EmptyOrderedIterator.<E>emptyOrderedIterator();
+        return EmptyOrderedIterator.emptyOrderedIterator();
     }
 
     /**
@@ -165,7 +125,7 @@ public static <E> OrderedIterator<E> emptyOrderedIterator() {
      * @return a map iterator over nothing
      */
     public static <K, V> MapIterator<K, V> emptyMapIterator() {
-        return EmptyMapIterator.<K, V>emptyMapIterator();
+        return EmptyMapIterator.emptyMapIterator();
     }
 
     /**
@@ -179,7 +139,7 @@ public static <K, V> MapIterator<K, V> emptyMapIterator() {
      * @return a map iterator over nothing
      */
     public static <K, V> OrderedMapIterator<K, V> emptyOrderedMapIterator() {
-        return EmptyOrderedMapIterator.<K, V>emptyOrderedMapIterator();
+        return EmptyOrderedMapIterator.emptyOrderedMapIterator();
     }
 
     // Singleton
@@ -889,6 +849,25 @@ public static <E> ZippingIterator<E> zippingIterator(final Iterator<? extends E>
         return new ZippingIterator<>(iterators);
     }
 
+    /**
+     * Gets an Iterator over the elements contained in a pair of Iterables in-tandem.
+     * <p>
+     * The returned iterator traverses the elements in {@code a} and {@code b} together until one of the iterators
+     * is exhausted.
+     * <p>
+     * The returned iterator does NOT support {@code remove()}.
+     *
+     * @param <L> the left elements' type
+     * @param <R> the right elements' type
+     * @param left the iterator for the left side elements
+     * @param right the iterator for the right side elements
+     * @return an iterator, to iterate over the decorated iterators together until one is exhausted
+     * @throws NullPointerException if any iterator is null
+     */
+    public static <L, R> PairedIterator<L, R> pairedIterator(final Iterator<L> left, Iterator<R> right) {
+        return PairedIterator.of(left, right);
+    }
+
     // Views
     /**
      * Gets an iterator that provides an iterator view of the given enumeration.

src/main/java/org/apache/commons/collections4/PairedIterable.java

@@ -0,0 +1,103 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.collections4;
+
+import org.apache.commons.collections4.iterators.PairedIterator;
+import org.apache.commons.collections4.iterators.PairedIterator.PairedItem;
+
+import java.util.Iterator;
+import java.util.stream.Stream;
+import java.util.stream.StreamSupport;
+
+import static java.util.Objects.requireNonNull;
+
+/**
+ * Provides iteration over the elements contained in a pair of Iterables in-tandem.
+ *
+ * <p>
+ * Given two {@link Iterable} instances {@code A} and {@code B}, the {@link #iterator} method on this
+ * iterator provide a Pair of {@code A.next()} and {@code B.next()} until one of the iterators is
+ * exhausted.
+ * </p>
+ * This can simplify zipping over two iterables using the for-each construct.
+ * Example usage:
+ * <pre>{@code
+ *   List<Integer> studentIds = ...
+ *   List<String> studentNames = ...
+ *
+ *   for (PairedItem<Integer, String> items : PairedIterable.of(studentIds, studentNames) {
+ *     Integer studentId = item.getLeft();
+ *     String studentName = item.getRight();
+ *     ...
+ *   }
+ * }</pre>
+ *
+ * @param <L> the left elements' type
+ * @param <R> the right elements' type
+ */
+public class PairedIterable<L, R> implements Iterable<PairedItem<L, R>> {
+
+    /**
+     * The left {@link Iterable}s to evaluate.
+     */
+    private final Iterable<L> leftIterable;
+
+    /**
+     * The right {@link Iterable}s to evaluate.
+     */
+    private final Iterable<R> rightIterable;
+
+    // Constructor
+    // ----------------------------------------------------------------------
+
+    /**
+     * Constructs a new {@code PairedIterable} that will provide iteration over two given iterables.
+     *
+     * @param leftIterable  the iterable for the left side element.
+     * @param rightIterable the iterable for the right side element.
+     * @throws NullPointerException if either iterator is null
+     */
+    public PairedIterable(Iterable<L> leftIterable, Iterable<R> rightIterable) {
+        this.leftIterable = requireNonNull(leftIterable);
+        this.rightIterable = requireNonNull(rightIterable);
+    }
+
+    /**
+     * Convenience static factory to construct the PairedIterable from provided
+     * {@link Iterable} sources.
+     *
+     * @param leftIterable  the iterable for the left side element.
+     * @param rightIterable the iterable for the right side element.
+     * @return the Iterable to iterate over the elements derived from the provided iterables.
+     * @throws NullPointerException if either iterables is null
+     */
+    public static <L, R> PairedIterable<L, R> of(Iterable<L> leftIterable, Iterable<R> rightIterable) {
+        return new PairedIterable<>(leftIterable, rightIterable);
+    }
+
+    // Iterable Methods
+    // -------------------------------------------------------------------
+
+    @Override
+    public Iterator<PairedItem<L, R>> iterator() {
+        return PairedIterator.ofIterables(leftIterable, rightIterable);
+    }
+
+    public Stream<PairedItem<L, R>> stream() {
+        return StreamSupport.stream(spliterator(), /*parallel=*/ false);
+    }
+}