COLLECTIONS-869: Add unwinding iterator

src/main/java/org/apache/commons/collections4/iterators/UnwindingIterator.java

@@ -0,0 +1,70 @@
+/*
+ * 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.iterators;
+
+import java.util.Iterator;
+import java.util.NoSuchElementException;
+
+/**
+ * A class to unwind an iterator of iterators.
+ * @param <T> The type of the object returned from the iterator.
+ * @since 4.5.0
+ */
+public class UnwindingIterator<T> implements Iterator<T> {
+    /** The innermost iterator */
+    private final Iterator<Iterator<T>> inner;
+    /** The iterator extracted from the inner iterator */
+    private Iterator<T> outer;
+
+    /**
+     * Constructs an iterator from an iterator of iterators.
+     * <p>
+     *     Unlike the IteratorChain<T> the inner iterators are not be constructed until needed so that any overhead
+     *     involved in constructing an enclosed Iterator<T> is amortized across the entire operation and not front
+     *     loaded on the constructor or first call.
+     * </p>
+     * @param it The iterator of iterators to unwind.
+     */
+    public UnwindingIterator(final Iterator<Iterator<T>> it) {
+        this.inner = it;
+    }
+
+    @Override
+    public boolean hasNext() {
+        if (outer == null) {
+            if (!inner.hasNext()) {
+                return false;
+            }
+            outer = inner.next();
+        }
+        while (!outer.hasNext()) {
+            if (!inner.hasNext()) {
+                return false;
+            }
+            outer = inner.next();
+        }
+        return true;
+    }
+
+    @Override
+    public T next() {
+        if (!hasNext()) {
+            throw new NoSuchElementException();
+        }
+        return outer.next();
+    }
+}

src/test/java/org/apache/commons/collections4/iterators/UnwindingIteratorTest.java

@@ -0,0 +1,76 @@
+/*
+ * 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.iterators;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.Arrays;
+import java.util.ArrayList;
+import java.util.Iterator;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+public class UnwindingIteratorTest {
+
+    @Test
+    public void simpleTest() {
+        List<Iterator<String>> lst = new ArrayList<>();
+        lst.add(Arrays.asList("Hello", "World").iterator());
+        lst.add(Arrays.asList("it", "is", "good", "to", "be", "here").iterator());
+        List<String> expected = Arrays.asList("Hello", "World", "it", "is", "good", "to", "be", "here");
+
+        Iterator<String> iter = new UnwindingIterator<>(lst.iterator());
+        List<String> actual = new ArrayList<>();
+        iter.forEachRemaining(actual::add);
+        assertEquals(actual, expected);
+    }
+
+    @Test
+    public void mixedTest() {
+        List<List<Number>> lst = new ArrayList<>();
+
+        List<Integer> iList = Arrays.asList(1, 3);
+        lst.add(Arrays.asList(3.14f, Math.sqrt(2.0)));
+
+        Iterator<Iterator<Number>> toBeUnwound = new Iterator<Iterator<Number>>() {
+            List<List<Number>> lst = Arrays.asList(
+                    Arrays.asList(1, 3),
+                    Arrays.asList(3.14F, Math.sqrt(2.0))
+            );
+            Iterator<List<Number>> lstIter = lst.iterator();
+
+            @Override
+            public boolean hasNext() {
+                return lstIter.hasNext();
+            }
+
+            @Override
+            public Iterator<Number> next() {
+                return lstIter.next().iterator();
+            }
+        };
+
+        List<Number> expected = Arrays.asList(1, 3, 3.14f, Math.sqrt(2.0));
+
+        Iterator<Number> iter = new UnwindingIterator<>(toBeUnwound);
+        List<Number> actual = new ArrayList<>();
+        iter.forEachRemaining(actual::add);
+        assertEquals(actual, expected);
+    }
+
+}