changeset 7598:a36b274075f5

More javadocs for Collectors
author briangoetz
date Sun, 10 Mar 2013 18:08:43 -0400
parents c436657091ee
children 988d94a4b83e
files src/share/classes/java/util/stream/Collectors.java
diffstat 1 files changed, 102 insertions(+), 21 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/Collectors.java	Sun Mar 10 17:25:18 2013 -0400
+++ b/src/share/classes/java/util/stream/Collectors.java	Sun Mar 10 18:08:43 2013 -0400
@@ -43,6 +43,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.ConcurrentMap;
 import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
 import java.util.function.BinaryOperator;
 import java.util.function.DoubleConsumer;
 import java.util.function.Function;
@@ -68,7 +69,7 @@
 
     private Collectors() {}
 
-    public static<T> BinaryOperator<T> throwingMerger() {
+    public static<T> BinaryOperator<T> throwingMergeFunction() {
         return (u,v) -> { throw new IllegalStateException(String.format("Duplicate key %s", u)); };
     }
 
@@ -200,7 +201,8 @@
      *                          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
+     * @return A {@code Collector} which collects elements into 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) {
@@ -211,7 +213,8 @@
      * Accumulate elements into a {@code List}.
      *
      * @param <T> The type of the input elements
-     * @return A {@code List} containing all the input elements, in encounter order
+     * @return A {@code Collector} which collects elements into a {@code List} containing all the input elements,
+     * in encounter order
      */
     public static<T>
     Collector<T, List<T>> toList() {
@@ -223,7 +226,7 @@
      * Accumulate elements into a {@code Set}.
      *
      * @param <T> The type of the input elements
-     * @return A {@code Set} containing all the input elements
+     * @return A {@code Collector} which collects elements into a {@code Set} containing all the input elements
      */
     public static<T>
     Collector<T, Set<T>> toSet() {
@@ -235,7 +238,8 @@
     /**
      * Accumulate {@code String} elements into a {@link StringBuilder}.
      *
-     * @return A {@code StringBuilder} containing all of the input elements concatenated in encounter order
+     * @return A {@code Collector} which collects {@code String} elements into 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));
@@ -244,7 +248,8 @@
     /**
      * Accumulate {@code String} elements into a {@link StringJoiner}, using the specified separator.
      *
-     * @return A {@code StringJoiner} containing all of the input elements concatenated in encounter order
+     * @return A {@code Collector} which collects String elements into 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),
@@ -281,7 +286,7 @@
      * @param <R> Result type of collector
      * @param mapper A function mapping {@code <T>} to {@code <U>}
      * @param downstream collector which will accept mapped values
-     * @return a collector which maps input values before accepting them
+     * @return A collector which applies a function to input values and then provides them to the downstream collector
      */
     public static <T, U, R> Collector<T, R>
     mapping(Function<? super T, ? extends U> mapper, Collector<U, R> downstream) {
@@ -549,10 +554,39 @@
         };
     }
 
+    /**
+     * Accumulate elements into a {@code Map} whose keys are the input elements and whose values are the
+     * result of a mapping function applied to the element.  If the input elements contains duplicates
+     * (according to {@link Object#equals(Object)}), an {@code IllegalStateException} is thrown when the
+     * collection operation is performed.
+     *
+     * @param <T> The type of the input elements, and the input type of the mapping function
+     * @param <U> The output type of the mapping function
+     * @param mapper The mapping function
+     * @return A {@code Collector} which collects elements into a {@code Map} whose keys are the input elements,
+     * and whose values are the result of applying the mapping function to the input element
+     */
     public static <T, U> Collector<T, Map<T,U>> toMap(Function<? super T, ? extends U> mapper) {
-        return toMap(mapper, HashMap::new, throwingMerger());
+        return toMap(mapper, HashMap::new, throwingMergeFunction());
     }
 
+    /**
+     * Accumulate elements into a {@code Map} whose keys are the input elements, and whose values are derived
+     * from the result of applying a mapping function to the input element.  If the input elements contains duplicates
+     * (according to {@link Object#equals(Object)}), the mapping function is applied to each equal element, and the
+     * results are merged with the provided merging function.
+     *
+     * @param mapper The mapping function
+     * @param mapSupplier A function which provides a new, empty {@code Map} into which the results will be inserted
+     * @param mergeFunction A merge function, used to resolve collisions between equal input elements, as supplied
+     *                      to {@link Map#merge(Object, Object, BiFunction)}
+     * @param <T> The type of the input elements, and the input type of the mapping function
+     * @param <U> The output type of the mapping function
+     * @param <M> The type of the resulting {@code Map}
+     * @return A {@code Collector} which collects elements into a {@code Map} whose keys are the input elements,
+     * and whose values are the result of applying the mapping function to all input elements equal to the key and
+     * combining them using the merge function
+     */
     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) {
@@ -560,10 +594,43 @@
         return new CollectorImpl<>(mapSupplier, accumulator, leftMapMerger(mergeFunction));
     }
 
+    /**
+     * Accumulate elements into a {@code ConcurrentMap} whose keys are the input elements and whose values are the
+     * result of a mapping function applied to the element.  If the input elements contains duplicates
+     * (according to {@link Object#equals(Object)}), an {@code IllegalStateException} is thrown when the
+     * collection operation is performed.
+     *
+     * <p>This is a <em>concurrent</em> Collector.  (TODO need reference).
+     *
+     * @param <T> The type of the input elements, and the input type of the mapping function
+     * @param <U> The output type of the mapping function
+     * @param mapper The mapping function
+     * @return A {@code Collector} which collects elements into a {@code Map} whose keys are the input elements,
+     * and whose values are the result of applying the mapping function to the input element
+     */
     public static <T, U> Collector<T, ConcurrentMap<T,U>> toConcurrentMap(Function<? super T, ? extends U> mapper) {
-        return toConcurrentMap(mapper, ConcurrentHashMap::new, throwingMerger());
+        return toConcurrentMap(mapper, ConcurrentHashMap::new, throwingMergeFunction());
     }
 
+    /**
+     * Accumulate elements into a {@code ConcurrentMap} whose keys are the input elements, and whose values are derived
+     * from the result of applying a mapping function to the input element.  If the input elements contains duplicates
+     * (according to {@link Object#equals(Object)}), the mapping function is applied to each equal element, and the
+     * results are merged with the provided merging function.
+     *
+     * <p>This is a <em>concurrent</em> Collector.  (TODO need reference).
+     *
+     * @param mapper The mapping function
+     * @param mapSupplier A function which provides a new, empty {@code Map} into which the results will be inserted
+     * @param mergeFunction A merge function, used to resolve collisions between equal input elements, as supplied
+     *                      to {@link Map#merge(Object, Object, BiFunction)}
+     * @param <T> The type of the input elements, and the input type of the mapping function
+     * @param <U> The output type of the mapping function
+     * @param <M> The type of the resulting {@code Map}
+     * @return A {@code Collector} which collects elements into a {@code Map} whose keys are the input elements,
+     * and whose values are the result of applying the mapping function to all input elements equal to the key and
+     * combining them using the merge function
+     */
     public static <T, U, M extends ConcurrentMap<T, U>>
     Collector<T, M> toConcurrentMap(Function<? super T, ? extends U> mapper,
                                     Supplier<M> mapSupplier,
@@ -645,6 +712,9 @@
         };
     }
 
+    /**
+     * A state object for collecting statistics such as count, min, max, sum, and average for {@code long} values.
+     */
     public static final class LongStatistics implements LongConsumer, IntConsumer {
         private long count;
         private long sum;
@@ -693,15 +763,18 @@
 
         @Override
         public String toString() {
-            return new StringJoiner(", ", this.getClass().getSimpleName() + "{", "}").
-                    add("count=" + getCount()).
-                    add("sum=" + getSum()).
-                    add("min=" + getMin()).
-                    add("max=" + getMax()).
-                    toString();
+            return new StringJoiner(", ", this.getClass().getSimpleName() + "{", "}")
+            .add("count=" + getCount())
+                    .add("sum=" + getSum())
+                    .add("min=" + getMin())
+                    .add("max=" + getMax())
+                    .toString();
         }
     }
 
+    /**
+     * A state object for collecting statistics such as count, min, max, sum, and average for {@code double} values.
+     */
     public static final class DoubleStatistics implements DoubleConsumer {
         private long count;
         private double sum;
@@ -745,20 +818,28 @@
 
         @Override
         public String toString() {
-            return new StringJoiner(", ", this.getClass().getSimpleName() + "{", "}").
-                    add("count=" + getCount()).
-                    add("sum=" + getSum()).
-                    add("min=" + getMin()).
-                    add("max=" + getMax()).
-                    toString();
+            return new StringJoiner(", ", this.getClass().getSimpleName() + "{", "}")
+                    .add("count=" + getCount())
+                    .add("sum=" + getSum())
+                    .add("min=" + getMin())
+                    .add("max=" + getMax())
+                    .toString();
         }
     }
 
+    /**
+     * Collect summary statistics for a set of {@code long} values.
+     * @return A {@code Collector} which summarizes {@code long} values into a {@link LongStatistics}
+     */
     public static Collector.OfLong<LongStatistics> toLongStatistics() {
         return new LongCollectorImpl<>(LongStatistics::new, LongStatistics::accept,
                                       (l, r) -> { l.combine(r); return l; });
     }
 
+    /**
+     * Collect summary statistics for a set of {@code double} values.
+     * @return A {@code Collector} which summarizes {@code double} values into a {@link DoubleStatistics}
+     */
     public static Collector.OfDouble<DoubleStatistics> toDoubleStatistics() {
         return new DoubleCollectorImpl<>(DoubleStatistics::new, DoubleStatistics::accept,
                                          (l, r) -> { l.combine(r); return l; });