Implement flatCollect on Collectors2.

Signed-off-by: Donald Raab <Donald.Raab@gs.com>

eclipse-collections/src/main/java/org/eclipse/collections/impl/collector/Collectors2.java

@@ -87,6 +87,7 @@
 import org.eclipse.collections.impl.map.mutable.primitive.ObjectLongHashMap;
 import org.eclipse.collections.impl.tuple.Tuples;
 import org.eclipse.collections.impl.tuple.primitive.PrimitiveTuples;
+import org.eclipse.collections.impl.utility.Iterate;
 
 /**
  * <p>A set of Collectors for Eclipse Collections types and algorithms.</p>
@@ -1390,6 +1391,33 @@ private Collectors2()
                 EMPTY_CHARACTERISTICS);
     }
 
+    /**
+     * The method {@code flatCollect} is a special case of {@link #collect(Function, Supplier)}. With {@code collect},
+     * when the {@link Function} returns a collection, the result is a collection of collections. {@code flatCollect} outputs
+     * a single "flattened" collection instead.  This method is commonly called flatMap.
+     * <p>Example:</p>
+     * <pre>{@code
+     * List<MutableList<String>> lists =
+     *     Lists.mutable.with(
+     *         Lists.mutable.with("a", "b"),
+     *         Lists.mutable.with("c", "d"),
+     *         Lists.mutable.with("e"));
+     *
+     * MutableList<String> flattened =
+     *     lists.stream().collect(Collectors2.flatCollect(l -> l, Lists.mutable::empty));
+     *
+     * Assert.assertEquals(Lists.mutable.with("a", "b", "c", "d", "e"), flattened);}</pre>
+     */
+    public static <T, V, R extends Collection<V>> Collector<T, ?, R> flatCollect(
+            Function<? super T, ? extends Iterable<V>> function, Supplier<R> supplier)
+    {
+        return Collector.of(
+                supplier,
+                (collection, each) -> Iterate.addAllTo(function.valueOf(each), collection),
+                Collectors2.mergeCollections(),
+                EMPTY_CHARACTERISTICS);
+    }
+
     /**
      * <p>Returns a new collection with the results of applying the specified function on each element of the source
      * collection with the specified parameter. This method is also commonly called transform or map. The new collection

unit-tests/src/test/java/org/eclipse/collections/impl/collector/Collectors2AdditionalTest.java

@@ -40,6 +40,7 @@
 import org.eclipse.collections.impl.factory.primitive.LongLists;
 import org.eclipse.collections.impl.factory.primitive.ShortLists;
 import org.eclipse.collections.impl.list.Interval;
+import org.eclipse.collections.impl.list.mutable.CompositeFastList;
 import org.eclipse.collections.impl.partition.bag.PartitionHashBag;
 import org.eclipse.collections.impl.partition.list.PartitionFastList;
 import org.eclipse.collections.impl.partition.set.PartitionUnifiedSet;
@@ -457,6 +458,58 @@ public void collectParallel()
                 this.bigData.parallelStream().collect(Collectors2.collect(Functions.getToString(), Bags.mutable::empty)));
     }
 
+    @Test
+    public void flatCollect()
+    {
+        MutableList<Interval> list = Lists.mutable.with(SMALL_INTERVAL, SMALL_INTERVAL, SMALL_INTERVAL);
+        Assert.assertEquals(
+                list.flatCollect(Functions.identity()),
+                list.stream().collect(Collectors2.flatCollect(Functions.identity(), Lists.mutable::empty))
+        );
+        Assert.assertEquals(
+                list.flatCollect(Functions.identity()),
+                list.stream().collect(Collectors2.flatCollect(Functions.identity(), CompositeFastList::new))
+        );
+        Assert.assertEquals(
+                list.toSet().flatCollect(Functions.identity()),
+                list.stream().collect(Collectors2.flatCollect(Functions.identity(), Sets.mutable::empty))
+        );
+        Assert.assertEquals(
+                list.toBag().flatCollect(Functions.identity()),
+                list.stream().collect(Collectors2.flatCollect(Functions.identity(), Bags.mutable::empty))
+        );
+        List<MutableList<String>> lists =
+                Lists.mutable.with(
+                        Lists.mutable.with("a", "b"),
+                        Lists.mutable.with("c", "d"),
+                        Lists.mutable.with("e"));
+        MutableList<String> flattened =
+                lists.stream().collect(Collectors2.flatCollect(l -> l, Lists.mutable::empty));
+        Assert.assertEquals(Lists.mutable.with("a", "b", "c", "d", "e"), flattened);
+    }
+
+    @Test
+    public void flatCollectParallel()
+    {
+        MutableList<Interval> list = Lists.mutable.withNValues(20000, () -> SMALL_INTERVAL);
+        Assert.assertEquals(
+                list.flatCollect(Functions.identity()),
+                list.parallelStream().collect(Collectors2.flatCollect(Functions.identity(), Lists.mutable::empty))
+        );
+        Assert.assertEquals(
+                list.flatCollect(Functions.identity()),
+                list.parallelStream().collect(Collectors2.flatCollect(Functions.identity(), CompositeFastList::new))
+        );
+        Assert.assertEquals(
+                list.toSet().flatCollect(Functions.identity()),
+                list.parallelStream().collect(Collectors2.flatCollect(Functions.identity(), Sets.mutable::empty))
+        );
+        Assert.assertEquals(
+                list.toBag().flatCollect(Functions.identity()),
+                list.parallelStream().collect(Collectors2.flatCollect(Functions.identity(), Bags.mutable::empty))
+        );
+    }
+
     @Test
     public void collectWith()
     {