changeset 7573:ec95dfc8b12c

Rename Collectors.joiningWith to toMap; reduce number of toMap forms
author briangoetz
date Thu, 07 Mar 2013 14:04:02 -0500
parents f4f14310067f
children f9bbfe0e351d
files src/share/classes/java/util/stream/Collectors.java
diffstat 1 files changed, 50 insertions(+), 15 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Collectors.java	Thu Mar 07 13:58:43 2013 +0100
+++ b/src/share/classes/java/util/stream/Collectors.java	Thu Mar 07 14:04:02 2013 -0500
@@ -56,7 +56,9 @@
 import java.util.function.ToLongFunction;
 
 /**
- * Collectors
+ * Implementations of {@link Collector} that implement various useful reduction operations, such as accumulating
+ * elements into collections, summarizing elements according to various criteria, etc.
+ *
  * @since 1.8
  */
 public final class Collectors {
@@ -188,17 +190,38 @@
         return new CollectorImpl<>(supplier, accumulator, (r1, r2) -> { merger.accept(r1, r2); return r1; });
     }
 
+    /**
+     * Accumulate elements into a new {@code Collection}, which is created by the provided factory.
+     *
+     * @param collectionFactory A {@code Supplier} which returns a new {@code Collection} of the appropriate type
+     *                          each time it is called
+     * @param <T> The type of the input elements
+     * @param <C> The type of the resulting {@code Collection}
+     * @return A {@code Collection} containing all the input elements, in encounter order
+     */
     public static<T, C extends Collection<T>>
     Collector<T,C> toCollection(Supplier<C> collectionFactory) {
         return leftCombining(collectionFactory, Collection::add, Collection::addAll);
     }
 
+    /**
+     * Accumulate elements into a new {@code List}.
+     *
+     * @param <T> The type of the input elements
+     * @return A {@code List} containing all the input elements, in encounter order
+     */
     public static<T>
     Collector<T,List<T>> toList() {
         // Consider a tree-based List?
         return toCollection(ArrayList::new);
     }
 
+    /**
+     * Accumulate elements into a new {@code Set}.
+     *
+     * @param <T> The type of the input elements
+     * @return A {@code Set} containing all the input elements
+     */
     public static<T>
     Collector<T,Set<T>> toSet() {
         // @@@ Declare that the collector is NOT_ORDERED so the reduce op can declare NOT_ORDERED in
@@ -206,10 +229,20 @@
         return toCollection(HashSet::new);
     }
 
+    /**
+     * Accumulate {@code String} elements into a new {@link StringBuilder}.
+     *
+     * @return A {@code StringBuilder} containing all of the input elements concatenated in encounter order
+     */
     public static Collector<String, StringBuilder> toStringBuilder() {
         return leftCombining(StringBuilder::new, StringBuilder::append, (sb, other) -> sb.append(other));
     }
 
+    /**
+     * Accumulate {@code String} elements into a new {@link StringJoiner}.
+     *
+     * @return A {@code StringJoiner} containing all of the input elements concatenated in encounter order
+     */
     public static Collector<CharSequence, StringJoiner> toStringJoiner(String separator) {
         return leftCombining(() -> new StringJoiner(separator),
                              StringJoiner::add,
@@ -224,6 +257,17 @@
         };
     }
 
+    /**
+     * Given a function from {@code T} to {@code U}, adapt a {@code Collector&lt;U,R>} to a
+     * {@code Collector&lt;T,R>} which applies the provided function to each input element.
+     *
+     * @param mapper
+     * @param downstream
+     * @param <T>
+     * @param <U>
+     * @param <R>
+     * @return
+     */
     public static <T, U, R> Collector<T, R>
     mapping(Function<? super T, ? extends U> mapper, Collector<U, R> downstream) {
         BiConsumer<R, U> downstreamAccumulator = downstream.accumulator();
@@ -317,22 +361,13 @@
         return new CollectorImpl<>(mapFactory, accumulator, Collectors.<K, D, M>leftMapMerger(reducer));
     }
 
-    public static <T, U> Collector<T, Map<T,U>> joiningWith(Function<? super T, ? extends U> mapper) {
-        return joiningWith(mapper, throwingMerger());
+    public static <T, U> Collector<T, Map<T,U>> toMap(Function<? super T, ? extends U> mapper) {
+        return toMap(mapper, HashMap::new, throwingMerger());
     }
 
-    public static <T, U> Collector<T, Map<T,U>> joiningWith(Function<? super T, ? extends U> mapper,
-                                                            BinaryOperator<U> mergeFunction) {
-        return joiningWith(mapper, mergeFunction, HashMap::new);
-    }
-
-    public static <T, U, M extends Map<T, U>> Collector<T, M> joiningWith(Function<? super T, ? extends U> mapper,
-                                                                          Supplier<M> mapSupplier) {
-        return joiningWith(mapper, throwingMerger(), mapSupplier);
-    }
-    public static <T, U, M extends Map<T, U>> Collector<T, M> joiningWith(Function<? super T, ? extends U> mapper,
-                                                                          BinaryOperator<U> mergeFunction,
-                                                                          Supplier<M> mapSupplier) {
+    public static <T, U, M extends Map<T, U>> Collector<T, M> toMap(Function<? super T, ? extends U> mapper,
+                                                                    Supplier<M> mapSupplier,
+                                                                    BinaryOperator<U> mergeFunction) {
         BiConsumer<M, T> accumulator = (map, value) -> map.merge(value, mapper.apply(value), mergeFunction);
         return new CollectorImpl<>(mapSupplier, accumulator, leftMapMerger(mergeFunction));
     }