1 /*
   2  * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 package java.util.stream;
  26 
  27 import java.util.AbstractMap;
  28 import java.util.AbstractSet;
  29 import java.util.ArrayList;
  30 import java.util.Arrays;
  31 import java.util.Collection;
  32 import java.util.Collections;
  33 import java.util.Comparator;
  34 import java.util.DoubleSummaryStatistics;
  35 import java.util.EnumSet;
  36 import java.util.HashMap;
  37 import java.util.HashSet;
  38 import java.util.IntSummaryStatistics;
  39 import java.util.Iterator;
  40 import java.util.List;
  41 import java.util.LongSummaryStatistics;
  42 import java.util.Map;
  43 import java.util.Objects;
  44 import java.util.Optional;
  45 import java.util.Set;
  46 import java.util.StringJoiner;
  47 import java.util.concurrent.ConcurrentHashMap;
  48 import java.util.concurrent.ConcurrentMap;
  49 import java.util.function.BiConsumer;
  50 import java.util.function.BiFunction;
  51 import java.util.function.BinaryOperator;
  52 import java.util.function.Consumer;
  53 import java.util.function.Function;
  54 import java.util.function.Predicate;
  55 import java.util.function.Supplier;
  56 import java.util.function.ToDoubleFunction;
  57 import java.util.function.ToIntFunction;
  58 import java.util.function.ToLongFunction;
  59 
  60 /**
  61  * Implementations of {@link Collector} that implement various useful reduction
  62  * operations, such as accumulating elements into collections, summarizing
  63  * elements according to various criteria, etc.
  64  *
  65  * <p>The following are examples of using the predefined collectors to perform
  66  * common mutable reduction tasks:
  67  *
  68  * <pre>{@code
  69  *     // Accumulate names into a List
  70  *     List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());
  71  *
  72  *     // Accumulate names into a TreeSet
  73  *     Set<String> set = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));
  74  *
  75  *     // Convert elements to strings and concatenate them, separated by commas
  76  *     String joined = things.stream()
  77  *                           .map(Object::toString)
  78  *                           .collect(Collectors.joining(", "));
  79  *
  80  *     // Compute sum of salaries of employee
  81  *     int total = employees.stream()
  82  *                          .collect(Collectors.summingInt(Employee::getSalary)));
  83  *
  84  *     // Group employees by department
  85  *     Map<Department, List<Employee>> byDept
  86  *         = employees.stream()
  87  *                    .collect(Collectors.groupingBy(Employee::getDepartment));
  88  *
  89  *     // Compute sum of salaries by department
  90  *     Map<Department, Integer> totalByDept
  91  *         = employees.stream()
  92  *                    .collect(Collectors.groupingBy(Employee::getDepartment,
  93  *                                                   Collectors.summingInt(Employee::getSalary)));
  94  *
  95  *     // Partition students into passing and failing
  96  *     Map<Boolean, List<Student>> passingFailing =
  97  *         students.stream()
  98  *                 .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD));
  99  *
 100  * }</pre>
 101  *
 102  * @since 1.8
 103  */
 104 public final class Collectors {
 105 
 106     static final Set<Collector.Characteristics> CH_CONCURRENT_ID
 107             = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT,
 108                                                      Collector.Characteristics.UNORDERED,
 109                                                      Collector.Characteristics.IDENTITY_FINISH));
 110     static final Set<Collector.Characteristics> CH_CONCURRENT_NOID
 111             = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT,
 112                                                      Collector.Characteristics.UNORDERED));
 113     static final Set<Collector.Characteristics> CH_ID
 114             = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH));
 115     static final Set<Collector.Characteristics> CH_UNORDERED_ID
 116             = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.UNORDERED,
 117                                                      Collector.Characteristics.IDENTITY_FINISH));
 118     static final Set<Collector.Characteristics> CH_NOID = Collections.emptySet();
 119 
 120     private Collectors() { }
 121 
 122     /**
 123      * Returns a merge function, suitable for use in
 124      * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or
 125      * {@link #toMap(Function, Function, BinaryOperator) toMap()}, which always
 126      * throws {@code IllegalStateException}.  This can be used to enforce the
 127      * assumption that the elements being collected are distinct.
 128      *
 129      * @param <T> the type of input arguments to the merge function
 130      * @return a merge function which always throw {@code IllegalStateException}
 131      */
 132     private static <T> BinaryOperator<T> throwingMerger() {
 133         return (u,v) -> { throw new IllegalStateException(String.format("Duplicate key %s", u)); };
 134     }
 135 
 136     @SuppressWarnings("unchecked")
 137     private static <I, R> Function<I, R> castingIdentity() {
 138         return i -> (R) i;
 139     }
 140 
 141     /**
 142      * Simple implementation class for {@code Collector}.
 143      *
 144      * @param <T> the type of elements to be collected
 145      * @param <R> the type of the result
 146      */
 147     static class CollectorImpl<T, A, R> implements Collector<T, A, R> {
 148         private final Supplier<A> supplier;
 149         private final BiConsumer<A, T> accumulator;
 150         private final BinaryOperator<A> combiner;
 151         private final Function<A, R> finisher;
 152         private final Set<Characteristics> characteristics;
 153 
 154         CollectorImpl(Supplier<A> supplier,
 155                       BiConsumer<A, T> accumulator,
 156                       BinaryOperator<A> combiner,
 157                       Function<A,R> finisher,
 158                       Set<Characteristics> characteristics) {
 159             this.supplier = supplier;
 160             this.accumulator = accumulator;
 161             this.combiner = combiner;
 162             this.finisher = finisher;
 163             this.characteristics = characteristics;
 164         }
 165 
 166         CollectorImpl(Supplier<A> supplier,
 167                       BiConsumer<A, T> accumulator,
 168                       BinaryOperator<A> combiner,
 169                       Set<Characteristics> characteristics) {
 170             this(supplier, accumulator, combiner, castingIdentity(), characteristics);
 171         }
 172 
 173         @Override
 174         public BiConsumer<A, T> accumulator() {
 175             return accumulator;
 176         }
 177 
 178         @Override
 179         public Supplier<A> supplier() {
 180             return supplier;
 181         }
 182 
 183         @Override
 184         public BinaryOperator<A> combiner() {
 185             return combiner;
 186         }
 187 
 188         @Override
 189         public Function<A, R> finisher() {
 190             return finisher;
 191         }
 192 
 193         @Override
 194         public Set<Characteristics> characteristics() {
 195             return characteristics;
 196         }
 197     }
 198 
 199     /**
 200      * Returns a {@code Collector} that accumulates the input elements into a
 201      * new {@code Collection}, in encounter order.  The {@code Collection} is
 202      * created by the provided factory.
 203      *
 204      * @param <T> the type of the input elements
 205      * @param <C> the type of the resulting {@code Collection}
 206      * @param collectionFactory a {@code Supplier} which returns a new, empty
 207      * {@code Collection} of the appropriate type
 208      * @return a {@code Collector} which collects all the input elements into a
 209      * {@code Collection}, in encounter order
 210      */
 211     public static <T, C extends Collection<T>>
 212     Collector<T, ?, C> toCollection(Supplier<C> collectionFactory) {
 213         return new CollectorImpl<>(collectionFactory, Collection<T>::add,
 214                                    (r1, r2) -> { r1.addAll(r2); return r1; },
 215                                    CH_ID);
 216     }
 217 
 218     /**
 219      * Returns a {@code Collector} that accumulates the input elements into a
 220      * new {@code List}. There are no guarantees on the type, mutability,
 221      * serializability, or thread-safety of the {@code List} returned; if more
 222      * control over the returned {@code List} is required, use {@link #toCollection(Supplier)}.
 223      *
 224      * @param <T> the type of the input elements
 225      * @return a {@code Collector} which collects all the input elements into a
 226      * {@code List}, in encounter order
 227      */
 228     public static <T>
 229     Collector<T, ?, List<T>> toList() {
 230         return new CollectorImpl<>((Supplier<List<T>>) ArrayList::new, List::add,
 231                                    (left, right) -> { left.addAll(right); return left; },
 232                                    CH_ID);
 233     }
 234 
 235     /**
 236      * Returns a {@code Collector} that accumulates the input elements into a
 237      * new {@code Set}. There are no guarantees on the type, mutability,
 238      * serializability, or thread-safety of the {@code Set} returned; if more
 239      * control over the returned {@code Set} is required, use
 240      * {@link #toCollection(Supplier)}.
 241      *
 242      * <p>This is an {@link Collector.Characteristics#UNORDERED unordered}
 243      * Collector.
 244      *
 245      * @param <T> the type of the input elements
 246      * @return a {@code Collector} which collects all the input elements into a
 247      * {@code Set}
 248      */
 249     public static <T>
 250     Collector<T, ?, Set<T>> toSet() {
 251         return new CollectorImpl<>((Supplier<Set<T>>) HashSet::new, Set::add,
 252                                    (left, right) -> { left.addAll(right); return left; },
 253                                    CH_UNORDERED_ID);
 254     }
 255 
 256     /**
 257      * Returns a {@code Collector} that concatenates the input elements into a
 258      * {@code String}, in encounter order.
 259      *
 260      * @return a {@code Collector} that concatenates the input elements into a
 261      * {@code String}, in encounter order
 262      */
 263     public static Collector<CharSequence, ?, String> joining() {
 264         return new CollectorImpl<CharSequence, StringBuilder, String>(
 265                 StringBuilder::new, StringBuilder::append,
 266                 (r1, r2) -> { r1.append(r2); return r1; },
 267                 StringBuilder::toString, CH_NOID);
 268     }
 269 
 270     /**
 271      * Returns a {@code Collector} that concatenates the input elements,
 272      * separated by the specified delimiter, in encounter order.
 273      *
 274      * @param delimiter the delimiter to be used between each element
 275      * @return A {@code Collector} which concatenates CharSequence elements,
 276      * separated by the specified delimiter, in encounter order
 277      */
 278     public static Collector<CharSequence, ?, String> joining(CharSequence delimiter) {
 279         return joining(delimiter, "", "");
 280     }
 281 
 282     /**
 283      * Returns a {@code Collector} that concatenates the input elements,
 284      * separated by the specified delimiter, with the specified prefix and
 285      * suffix, in encounter order.
 286      *
 287      * @param delimiter the delimiter to be used between each element
 288      * @param  prefix the sequence of characters to be used at the beginning
 289      *                of the joined result
 290      * @param  suffix the sequence of characters to be used at the end
 291      *                of the joined result
 292      * @return A {@code Collector} which concatenates CharSequence elements,
 293      * separated by the specified delimiter, in encounter order
 294      */
 295     public static Collector<CharSequence, ?, String> joining(CharSequence delimiter,
 296                                                              CharSequence prefix,
 297                                                              CharSequence suffix) {
 298         return new CollectorImpl<>(
 299                 () -> new StringJoiner(delimiter, prefix, suffix),
 300                 StringJoiner::add, StringJoiner::merge,
 301                 StringJoiner::toString, CH_NOID);
 302     }
 303 
 304     /**
 305      * {@code BinaryOperator<Map>} that merges the contents of its right
 306      * argument into its left argument, using the provided merge function to
 307      * handle duplicate keys.
 308      *
 309      * @param <K> type of the map keys
 310      * @param <V> type of the map values
 311      * @param <M> type of the map
 312      * @param mergeFunction A merge function suitable for
 313      * {@link Map#merge(Object, Object, BiFunction) Map.merge()}
 314      * @return a merge function for two maps
 315      */
 316     private static <K, V, M extends Map<K,V>>
 317     BinaryOperator<M> mapMerger(BinaryOperator<V> mergeFunction) {
 318         return (m1, m2) -> {
 319             for (Map.Entry<K,V> e : m2.entrySet())
 320                 m1.merge(e.getKey(), e.getValue(), mergeFunction);
 321             return m1;
 322         };
 323     }
 324 
 325     /**
 326      * Adapts a {@code Collector} accepting elements of type {@code U} to one
 327      * accepting elements of type {@code T} by applying a mapping function to
 328      * each input element before accumulation.
 329      *
 330      * @apiNote
 331      * The {@code mapping()} collectors are most useful when used in a
 332      * multi-level reduction, such as downstream of a {@code groupingBy} or
 333      * {@code partitioningBy}.  For example, given a stream of
 334      * {@code Person}, to accumulate the set of last names in each city:
 335      * <pre>{@code
 336      *     Map<City, Set<String>> lastNamesByCity
 337      *         = people.stream().collect(groupingBy(Person::getCity,
 338      *                                              mapping(Person::getLastName, toSet())));
 339      * }</pre>
 340      *
 341      * @param <T> the type of the input elements
 342      * @param <U> type of elements accepted by downstream collector
 343      * @param <A> intermediate accumulation type of the downstream collector
 344      * @param <R> result type of collector
 345      * @param mapper a function to be applied to the input elements
 346      * @param downstream a collector which will accept mapped values
 347      * @return a collector which applies the mapping function to the input
 348      * elements and provides the mapped results to the downstream collector
 349      */
 350     public static <T, U, A, R>
 351     Collector<T, ?, R> mapping(Function<? super T, ? extends U> mapper,
 352                                Collector<? super U, A, R> downstream) {
 353         BiConsumer<A, ? super U> downstreamAccumulator = downstream.accumulator();
 354         return new CollectorImpl<>(downstream.supplier(),
 355                                    (r, t) -> downstreamAccumulator.accept(r, mapper.apply(t)),
 356                                    downstream.combiner(), downstream.finisher(),
 357                                    downstream.characteristics());
 358     }
 359 
 360     /**
 361      * Adapts a {@code Collector} to perform an additional finishing
 362      * transformation.  For example, one could adapt the {@link #toList()}
 363      * collector to always produce an immutable list with:
 364      * <pre>{@code
 365      *     List<String> people
 366      *         = people.stream().collect(collectingAndThen(toList(), Collections::unmodifiableList));
 367      * }</pre>
 368      *
 369      * @param <T> the type of the input elements
 370      * @param <A> intermediate accumulation type of the downstream collector
 371      * @param <R> result type of the downstream collector
 372      * @param <RR> result type of the resulting collector
 373      * @param downstream a collector
 374      * @param finisher a function to be applied to the final result of the downstream collector
 375      * @return a collector which performs the action of the downstream collector,
 376      * followed by an additional finishing step
 377      */
 378     public static<T,A,R,RR> Collector<T,A,RR> collectingAndThen(Collector<T,A,R> downstream,
 379                                                                 Function<R,RR> finisher) {
 380         Set<Collector.Characteristics> characteristics = downstream.characteristics();
 381         if (characteristics.contains(Collector.Characteristics.IDENTITY_FINISH)) {
 382             if (characteristics.size() == 1)
 383                 characteristics = Collectors.CH_NOID;
 384             else {
 385                 characteristics = EnumSet.copyOf(characteristics);
 386                 characteristics.remove(Collector.Characteristics.IDENTITY_FINISH);
 387                 characteristics = Collections.unmodifiableSet(characteristics);
 388             }
 389         }
 390         return new CollectorImpl<>(downstream.supplier(),
 391                                    downstream.accumulator(),
 392                                    downstream.combiner(),
 393                                    downstream.finisher().andThen(finisher),
 394                                    characteristics);
 395     }
 396 
 397     /**
 398      * Returns a {@code Collector} accepting elements of type {@code T} that
 399      * counts the number of input elements.  If no elements are present, the
 400      * result is 0.
 401      *
 402      * @implSpec
 403      * This produces a result equivalent to:
 404      * <pre>{@code
 405      *     reducing(0L, e -> 1L, Long::sum)
 406      * }</pre>
 407      *
 408      * @param <T> the type of the input elements
 409      * @return a {@code Collector} that counts the input elements
 410      */
 411     public static <T> Collector<T, ?, Long>
 412     counting() {
 413         return reducing(0L, e -> 1L, Long::sum);
 414     }
 415 
 416     /**
 417      * Returns a {@code Collector} that produces the minimal element according
 418      * to a given {@code Comparator}, described as an {@code Optional<T>}.
 419      *
 420      * @implSpec
 421      * This produces a result equivalent to:
 422      * <pre>{@code
 423      *     reducing(BinaryOperator.minBy(comparator))
 424      * }</pre>
 425      *
 426      * @param <T> the type of the input elements
 427      * @param comparator a {@code Comparator} for comparing elements
 428      * @return a {@code Collector} that produces the minimal value
 429      */
 430     public static <T> Collector<T, ?, Optional<T>>
 431     minBy(Comparator<? super T> comparator) {
 432         return reducing(BinaryOperator.minBy(comparator));
 433     }
 434 
 435     /**
 436      * Returns a {@code Collector} that produces the maximal element according
 437      * to a given {@code Comparator}, described as an {@code Optional<T>}.
 438      *
 439      * @implSpec
 440      * This produces a result equivalent to:
 441      * <pre>{@code
 442      *     reducing(BinaryOperator.maxBy(comparator))
 443      * }</pre>
 444      *
 445      * @param <T> the type of the input elements
 446      * @param comparator a {@code Comparator} for comparing elements
 447      * @return a {@code Collector} that produces the maximal value
 448      */
 449     public static <T> Collector<T, ?, Optional<T>>
 450     maxBy(Comparator<? super T> comparator) {
 451         return reducing(BinaryOperator.maxBy(comparator));
 452     }
 453 
 454     /**
 455      * Returns a {@code Collector} that produces the sum of a integer-valued
 456      * function applied to the input elements.  If no elements are present,
 457      * the result is 0.
 458      *
 459      * @param <T> the type of the input elements
 460      * @param mapper a function extracting the property to be summed
 461      * @return a {@code Collector} that produces the sum of a derived property
 462      */
 463     public static <T> Collector<T, ?, Integer>
 464     summingInt(ToIntFunction<? super T> mapper) {
 465         return new CollectorImpl<>(
 466                 () -> new int[1],
 467                 (a, t) -> { a[0] += mapper.applyAsInt(t); },
 468                 (a, b) -> { a[0] += b[0]; return a; },
 469                 a -> a[0], CH_NOID);
 470     }
 471 
 472     /**
 473      * Returns a {@code Collector} that produces the sum of a long-valued
 474      * function applied to the input elements.  If no elements are present,
 475      * the result is 0.
 476      *
 477      * @param <T> the type of the input elements
 478      * @param mapper a function extracting the property to be summed
 479      * @return a {@code Collector} that produces the sum of a derived property
 480      */
 481     public static <T> Collector<T, ?, Long>
 482     summingLong(ToLongFunction<? super T> mapper) {
 483         return new CollectorImpl<>(
 484                 () -> new long[1],
 485                 (a, t) -> { a[0] += mapper.applyAsLong(t); },
 486                 (a, b) -> { a[0] += b[0]; return a; },
 487                 a -> a[0], CH_NOID);
 488     }
 489 
 490     /**
 491      * Returns a {@code Collector} that produces the sum of a double-valued
 492      * function applied to the input elements.  If no elements are present,
 493      * the result is 0.
 494      *
 495      * <p>The sum returned can vary depending upon the order in which
 496      * values are recorded, due to accumulated rounding error in
 497      * addition of values of differing magnitudes. Values sorted by increasing
 498      * absolute magnitude tend to yield more accurate results.  If any recorded
 499      * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
 500      * sum will be {@code NaN}.
 501      *
 502      * @param <T> the type of the input elements
 503      * @param mapper a function extracting the property to be summed
 504      * @return a {@code Collector} that produces the sum of a derived property
 505      */
 506     public static <T> Collector<T, ?, Double>
 507     summingDouble(ToDoubleFunction<? super T> mapper) {
 508         return new CollectorImpl<>(
 509                 () -> new double[1],
 510                 (a, t) -> { a[0] += mapper.applyAsDouble(t); },
 511                 (a, b) -> { a[0] += b[0]; return a; },
 512                 a -> a[0], CH_NOID);
 513     }
 514 
 515     /**
 516      * Returns a {@code Collector} that produces the arithmetic mean of an integer-valued
 517      * function applied to the input elements.  If no elements are present,
 518      * the result is 0.
 519      *
 520      * @param <T> the type of the input elements
 521      * @param mapper a function extracting the property to be summed
 522      * @return a {@code Collector} that produces the sum of a derived property
 523      */
 524     public static <T> Collector<T, ?, Double>
 525     averagingInt(ToIntFunction<? super T> mapper) {
 526         return new CollectorImpl<>(
 527                 () -> new long[2],
 528                 (a, t) -> { a[0] += mapper.applyAsInt(t); a[1]++; },
 529                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
 530                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
 531     }
 532 
 533     /**
 534      * Returns a {@code Collector} that produces the arithmetic mean of a long-valued
 535      * function applied to the input elements.  If no elements are present,
 536      * the result is 0.
 537      *
 538      * @param <T> the type of the input elements
 539      * @param mapper a function extracting the property to be summed
 540      * @return a {@code Collector} that produces the sum of a derived property
 541      */
 542     public static <T> Collector<T, ?, Double>
 543     averagingLong(ToLongFunction<? super T> mapper) {
 544         return new CollectorImpl<>(
 545                 () -> new long[2],
 546                 (a, t) -> { a[0] += mapper.applyAsLong(t); a[1]++; },
 547                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
 548                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
 549     }
 550 
 551     /**
 552      * Returns a {@code Collector} that produces the arithmetic mean of a double-valued
 553      * function applied to the input elements.  If no elements are present,
 554      * the result is 0.
 555      *
 556      * <p>The average returned can vary depending upon the order in which
 557      * values are recorded, due to accumulated rounding error in
 558      * addition of values of differing magnitudes. Values sorted by increasing
 559      * absolute magnitude tend to yield more accurate results.  If any recorded
 560      * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
 561      * average will be {@code NaN}.
 562      *
 563      * @param <T> the type of the input elements
 564      * @param mapper a function extracting the property to be summed
 565      * @return a {@code Collector} that produces the sum of a derived property
 566      */
 567     public static <T> Collector<T, ?, Double>
 568     averagingDouble(ToDoubleFunction<? super T> mapper) {
 569         return new CollectorImpl<>(
 570                 () -> new double[2],
 571                 (a, t) -> { a[0] += mapper.applyAsDouble(t); a[1]++; },
 572                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
 573                 a -> (a[1] == 0) ? 0.0d : a[0] / a[1], CH_NOID);
 574     }
 575 
 576     /**
 577      * Returns a {@code Collector} which performs a reduction of its
 578      * input elements under a specified {@code BinaryOperator} using the
 579      * provided identity.
 580      *
 581      * @apiNote
 582      * The {@code reducing()} collectors are most useful when used in a
 583      * multi-level reduction, downstream of {@code groupingBy} or
 584      * {@code partitioningBy}.  To perform a simple reduction on a stream,
 585      * use {@link Stream#reduce(Object, BinaryOperator)}} instead.
 586      *
 587      * @param <T> element type for the input and output of the reduction
 588      * @param identity the identity value for the reduction (also, the value
 589      *                 that is returned when there are no input elements)
 590      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
 591      * @return a {@code Collector} which implements the reduction operation
 592      *
 593      * @see #reducing(BinaryOperator)
 594      * @see #reducing(Object, Function, BinaryOperator)
 595      */
 596     public static <T> Collector<T, ?, T>
 597     reducing(T identity, BinaryOperator<T> op) {
 598         return new CollectorImpl<>(
 599                 boxSupplier(identity),
 600                 (a, t) -> { a[0] = op.apply(a[0], t); },
 601                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
 602                 a -> a[0],
 603                 CH_NOID);
 604     }
 605 
 606     @SuppressWarnings("unchecked")
 607     private static <T> Supplier<T[]> boxSupplier(T identity) {
 608         return () -> (T[]) new Object[] { identity };
 609     }
 610 
 611     /**
 612      * Returns a {@code Collector} which performs a reduction of its
 613      * input elements under a specified {@code BinaryOperator}.  The result
 614      * is described as an {@code Optional<T>}.
 615      *
 616      * @apiNote
 617      * The {@code reducing()} collectors are most useful when used in a
 618      * multi-level reduction, downstream of {@code groupingBy} or
 619      * {@code partitioningBy}.  To perform a simple reduction on a stream,
 620      * use {@link Stream#reduce(BinaryOperator)} instead.
 621      *
 622      * <p>For example, given a stream of {@code Person}, to calculate tallest
 623      * person in each city:
 624      * <pre>{@code
 625      *     Comparator<Person> byHeight = Comparator.comparing(Person::getHeight);
 626      *     Map<City, Person> tallestByCity
 627      *         = people.stream().collect(groupingBy(Person::getCity, reducing(BinaryOperator.maxBy(byHeight))));
 628      * }</pre>
 629      *
 630      * @param <T> element type for the input and output of the reduction
 631      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
 632      * @return a {@code Collector} which implements the reduction operation
 633      *
 634      * @see #reducing(Object, BinaryOperator)
 635      * @see #reducing(Object, Function, BinaryOperator)
 636      */
 637     public static <T> Collector<T, ?, Optional<T>>
 638     reducing(BinaryOperator<T> op) {
 639         class OptionalBox implements Consumer<T> {
 640             T value = null;
 641             boolean present = false;
 642 
 643             @Override
 644             public void accept(T t) {
 645                 if (present) {
 646                     value = op.apply(value, t);
 647                 }
 648                 else {
 649                     value = t;
 650                     present = true;
 651                 }
 652             }
 653         }
 654 
 655         return new CollectorImpl<T, OptionalBox, Optional<T>>(
 656                 OptionalBox::new, OptionalBox::accept,
 657                 (a, b) -> { if (b.present) a.accept(b.value); return a; },
 658                 a -> Optional.ofNullable(a.value), CH_NOID);
 659     }
 660 
 661     /**
 662      * Returns a {@code Collector} which performs a reduction of its
 663      * input elements under a specified mapping function and
 664      * {@code BinaryOperator}. This is a generalization of
 665      * {@link #reducing(Object, BinaryOperator)} which allows a transformation
 666      * of the elements before reduction.
 667      *
 668      * @apiNote
 669      * The {@code reducing()} collectors are most useful when used in a
 670      * multi-level reduction, downstream of {@code groupingBy} or
 671      * {@code partitioningBy}.  To perform a simple map-reduce on a stream,
 672      * use {@link Stream#map(Function)} and {@link Stream#reduce(Object, BinaryOperator)}
 673      * instead.
 674      *
 675      * <p>For example, given a stream of {@code Person}, to calculate the longest
 676      * last name of residents in each city:
 677      * <pre>{@code
 678      *     Comparator<String> byLength = Comparator.comparing(String::length);
 679      *     Map<City, String> longestLastNameByCity
 680      *         = people.stream().collect(groupingBy(Person::getCity,
 681      *                                              reducing(Person::getLastName, BinaryOperator.maxBy(byLength))));
 682      * }</pre>
 683      *
 684      * @param <T> the type of the input elements
 685      * @param <U> the type of the mapped values
 686      * @param identity the identity value for the reduction (also, the value
 687      *                 that is returned when there are no input elements)
 688      * @param mapper a mapping function to apply to each input value
 689      * @param op a {@code BinaryOperator<U>} used to reduce the mapped values
 690      * @return a {@code Collector} implementing the map-reduce operation
 691      *
 692      * @see #reducing(Object, BinaryOperator)
 693      * @see #reducing(BinaryOperator)
 694      */
 695     public static <T, U>
 696     Collector<T, ?, U> reducing(U identity,
 697                                 Function<? super T, ? extends U> mapper,
 698                                 BinaryOperator<U> op) {
 699         return new CollectorImpl<>(
 700                 boxSupplier(identity),
 701                 (a, t) -> { a[0] = op.apply(a[0], mapper.apply(t)); },
 702                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
 703                 a -> a[0], CH_NOID);
 704     }
 705 
 706     /**
 707      * Returns a {@code Collector} implementing a "group by" operation on
 708      * input elements of type {@code T}, grouping elements according to a
 709      * classification function, and returning the results in a {@code Map}.
 710      *
 711      * <p>The classification function maps elements to some key type {@code K}.
 712      * The collector produces a {@code Map<K, List<T>>} whose keys are the
 713      * values resulting from applying the classification function to the input
 714      * elements, and whose corresponding values are {@code List}s containing the
 715      * input elements which map to the associated key under the classification
 716      * function.
 717      *
 718      * <p>There are no guarantees on the type, mutability, serializability, or
 719      * thread-safety of the {@code Map} or {@code List} objects returned.
 720      * @implSpec
 721      * This produces a result similar to:
 722      * <pre>{@code
 723      *     groupingBy(classifier, toList());
 724      * }</pre>
 725      *
 726      * @implNote
 727      * The returned {@code Collector} is not concurrent.  For parallel stream
 728      * pipelines, the {@code combiner} function operates by merging the keys
 729      * from one map into another, which can be an expensive operation.  If
 730      * preservation of the order in which elements appear in the resulting {@code Map}
 731      * collector is not required, using {@link #groupingByConcurrent(Function)}
 732      * may offer better parallel performance.
 733      *
 734      * @param <T> the type of the input elements
 735      * @param <K> the type of the keys
 736      * @param classifier the classifier function mapping input elements to keys
 737      * @return a {@code Collector} implementing the group-by operation
 738      *
 739      * @see #groupingBy(Function, Collector)
 740      * @see #groupingBy(Function, Supplier, Collector)
 741      * @see #groupingByConcurrent(Function)
 742      */
 743     public static <T, K> Collector<T, ?, Map<K, List<T>>>
 744     groupingBy(Function<? super T, ? extends K> classifier) {
 745         return groupingBy(classifier, toList());
 746     }
 747 
 748     /**
 749      * Returns a {@code Collector} implementing a cascaded "group by" operation
 750      * on input elements of type {@code T}, grouping elements according to a
 751      * classification function, and then performing a reduction operation on
 752      * the values associated with a given key using the specified downstream
 753      * {@code Collector}.
 754      *
 755      * <p>The classification function maps elements to some key type {@code K}.
 756      * The downstream collector operates on elements of type {@code T} and
 757      * produces a result of type {@code D}. The resulting collector produces a
 758      * {@code Map<K, D>}.
 759      *
 760      * <p>There are no guarantees on the type, mutability,
 761      * serializability, or thread-safety of the {@code Map} returned.
 762      *
 763      * <p>For example, to compute the set of last names of people in each city:
 764      * <pre>{@code
 765      *     Map<City, Set<String>> namesByCity
 766      *         = people.stream().collect(groupingBy(Person::getCity,
 767      *                                              mapping(Person::getLastName, toSet())));
 768      * }</pre>
 769      *
 770      * @implNote
 771      * The returned {@code Collector} is not concurrent.  For parallel stream
 772      * pipelines, the {@code combiner} function operates by merging the keys
 773      * from one map into another, which can be an expensive operation.  If
 774      * preservation of the order in which elements are presented to the downstream
 775      * collector is not required, using {@link #groupingByConcurrent(Function, Collector)}
 776      * may offer better parallel performance.
 777      *
 778      * @param <T> the type of the input elements
 779      * @param <K> the type of the keys
 780      * @param <A> the intermediate accumulation type of the downstream collector
 781      * @param <D> the result type of the downstream reduction
 782      * @param classifier a classifier function mapping input elements to keys
 783      * @param downstream a {@code Collector} implementing the downstream reduction
 784      * @return a {@code Collector} implementing the cascaded group-by operation
 785      * @see #groupingBy(Function)
 786      *
 787      * @see #groupingBy(Function, Supplier, Collector)
 788      * @see #groupingByConcurrent(Function, Collector)
 789      */
 790     public static <T, K, A, D>
 791     Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,
 792                                           Collector<? super T, A, D> downstream) {
 793         return groupingBy(classifier, HashMap::new, downstream);
 794     }
 795 
 796     /**
 797      * Returns a {@code Collector} implementing a cascaded "group by" operation
 798      * on input elements of type {@code T}, grouping elements according to a
 799      * classification function, and then performing a reduction operation on
 800      * the values associated with a given key using the specified downstream
 801      * {@code Collector}.  The {@code Map} produced by the Collector is created
 802      * with the supplied factory function.
 803      *
 804      * <p>The classification function maps elements to some key type {@code K}.
 805      * The downstream collector operates on elements of type {@code T} and
 806      * produces a result of type {@code D}. The resulting collector produces a
 807      * {@code Map<K, D>}.
 808      *
 809      * <p>For example, to compute the set of last names of people in each city,
 810      * where the city names are sorted:
 811      * <pre>{@code
 812      *     Map<City, Set<String>> namesByCity
 813      *         = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
 814      *                                              mapping(Person::getLastName, toSet())));
 815      * }</pre>
 816      *
 817      * @implNote
 818      * The returned {@code Collector} is not concurrent.  For parallel stream
 819      * pipelines, the {@code combiner} function operates by merging the keys
 820      * from one map into another, which can be an expensive operation.  If
 821      * preservation of the order in which elements are presented to the downstream
 822      * collector is not required, using {@link #groupingByConcurrent(Function, Supplier, Collector)}
 823      * may offer better parallel performance.
 824      *
 825      * @param <T> the type of the input elements
 826      * @param <K> the type of the keys
 827      * @param <A> the intermediate accumulation type of the downstream collector
 828      * @param <D> the result type of the downstream reduction
 829      * @param <M> the type of the resulting {@code Map}
 830      * @param classifier a classifier function mapping input elements to keys
 831      * @param downstream a {@code Collector} implementing the downstream reduction
 832      * @param mapFactory a function which, when called, produces a new empty
 833      *                   {@code Map} of the desired type
 834      * @return a {@code Collector} implementing the cascaded group-by operation
 835      *
 836      * @see #groupingBy(Function, Collector)
 837      * @see #groupingBy(Function)
 838      * @see #groupingByConcurrent(Function, Supplier, Collector)
 839      */
 840     public static <T, K, D, A, M extends Map<K, D>>
 841     Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier,
 842                                   Supplier<M> mapFactory,
 843                                   Collector<? super T, A, D> downstream) {
 844         Supplier<A> downstreamSupplier = downstream.supplier();
 845         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
 846         BiConsumer<Map<K, A>, T> accumulator = (m, t) -> {
 847             K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
 848             A container = m.computeIfAbsent(key, k -> downstreamSupplier.get());
 849             downstreamAccumulator.accept(container, t);
 850         };
 851         BinaryOperator<Map<K, A>> merger = Collectors.<K, A, Map<K, A>>mapMerger(downstream.combiner());
 852         @SuppressWarnings("unchecked")
 853         Supplier<Map<K, A>> mangledFactory = (Supplier<Map<K, A>>) mapFactory;
 854 
 855         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
 856             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_ID);
 857         }
 858         else {
 859             @SuppressWarnings("unchecked")
 860             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
 861             Function<Map<K, A>, M> finisher = intermediate -> {
 862                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
 863                 @SuppressWarnings("unchecked")
 864                 M castResult = (M) intermediate;
 865                 return castResult;
 866             };
 867             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_NOID);
 868         }
 869     }
 870 
 871     /**
 872      * Returns a concurrent {@code Collector} implementing a "group by"
 873      * operation on input elements of type {@code T}, grouping elements
 874      * according to a classification function.
 875      *
 876      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 877      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 878      *
 879      * <p>The classification function maps elements to some key type {@code K}.
 880      * The collector produces a {@code ConcurrentMap<K, List<T>>} whose keys are the
 881      * values resulting from applying the classification function to the input
 882      * elements, and whose corresponding values are {@code List}s containing the
 883      * input elements which map to the associated key under the classification
 884      * function.
 885      *
 886      * <p>There are no guarantees on the type, mutability, or serializability
 887      * of the {@code Map} or {@code List} objects returned, or of the
 888      * thread-safety of the {@code List} objects returned.
 889      * @implSpec
 890      * This produces a result similar to:
 891      * <pre>{@code
 892      *     groupingByConcurrent(classifier, toList());
 893      * }</pre>
 894      *
 895      * @param <T> the type of the input elements
 896      * @param <K> the type of the keys
 897      * @param classifier a classifier function mapping input elements to keys
 898      * @return a concurrent, unordered {@code Collector} implementing the group-by operation
 899      *
 900      * @see #groupingBy(Function)
 901      * @see #groupingByConcurrent(Function, Collector)
 902      * @see #groupingByConcurrent(Function, Supplier, Collector)
 903      */
 904     public static <T, K>
 905     Collector<T, ?, ConcurrentMap<K, List<T>>>
 906     groupingByConcurrent(Function<? super T, ? extends K> classifier) {
 907         return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList());
 908     }
 909 
 910     /**
 911      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
 912      * operation on input elements of type {@code T}, grouping elements
 913      * according to a classification function, and then performing a reduction
 914      * operation on the values associated with a given key using the specified
 915      * downstream {@code Collector}.
 916      *
 917      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 918      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 919      *
 920      * <p>The classification function maps elements to some key type {@code K}.
 921      * The downstream collector operates on elements of type {@code T} and
 922      * produces a result of type {@code D}. The resulting collector produces a
 923      * {@code Map<K, D>}.
 924      *
 925      * <p>For example, to compute the set of last names of people in each city,
 926      * where the city names are sorted:
 927      * <pre>{@code
 928      *     ConcurrentMap<City, Set<String>> namesByCity
 929      *         = people.stream().collect(groupingByConcurrent(Person::getCity,
 930      *                                                        mapping(Person::getLastName, toSet())));
 931      * }</pre>
 932      *
 933      * @param <T> the type of the input elements
 934      * @param <K> the type of the keys
 935      * @param <A> the intermediate accumulation type of the downstream collector
 936      * @param <D> the result type of the downstream reduction
 937      * @param classifier a classifier function mapping input elements to keys
 938      * @param downstream a {@code Collector} implementing the downstream reduction
 939      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
 940      *
 941      * @see #groupingBy(Function, Collector)
 942      * @see #groupingByConcurrent(Function)
 943      * @see #groupingByConcurrent(Function, Supplier, Collector)
 944      */
 945     public static <T, K, A, D>
 946     Collector<T, ?, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier,
 947                                                               Collector<? super T, A, D> downstream) {
 948         return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream);
 949     }
 950 
 951     /**
 952      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
 953      * operation on input elements of type {@code T}, grouping elements
 954      * according to a classification function, and then performing a reduction
 955      * operation on the values associated with a given key using the specified
 956      * downstream {@code Collector}.  The {@code ConcurrentMap} produced by the
 957      * Collector is created with the supplied factory function.
 958      *
 959      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 960      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 961      *
 962      * <p>The classification function maps elements to some key type {@code K}.
 963      * The downstream collector operates on elements of type {@code T} and
 964      * produces a result of type {@code D}. The resulting collector produces a
 965      * {@code Map<K, D>}.
 966      *
 967      * <p>For example, to compute the set of last names of people in each city,
 968      * where the city names are sorted:
 969      * <pre>{@code
 970      *     ConcurrentMap<City, Set<String>> namesByCity
 971      *         = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
 972      *                                              mapping(Person::getLastName, toSet())));
 973      * }</pre>
 974      *
 975      *
 976      * @param <T> the type of the input elements
 977      * @param <K> the type of the keys
 978      * @param <A> the intermediate accumulation type of the downstream collector
 979      * @param <D> the result type of the downstream reduction
 980      * @param <M> the type of the resulting {@code ConcurrentMap}
 981      * @param classifier a classifier function mapping input elements to keys
 982      * @param downstream a {@code Collector} implementing the downstream reduction
 983      * @param mapFactory a function which, when called, produces a new empty
 984      *                   {@code ConcurrentMap} of the desired type
 985      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
 986      *
 987      * @see #groupingByConcurrent(Function)
 988      * @see #groupingByConcurrent(Function, Collector)
 989      * @see #groupingBy(Function, Supplier, Collector)
 990      */
 991     public static <T, K, A, D, M extends ConcurrentMap<K, D>>
 992     Collector<T, ?, M> groupingByConcurrent(Function<? super T, ? extends K> classifier,
 993                                             Supplier<M> mapFactory,
 994                                             Collector<? super T, A, D> downstream) {
 995         Supplier<A> downstreamSupplier = downstream.supplier();
 996         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
 997         BinaryOperator<ConcurrentMap<K, A>> merger = Collectors.<K, A, ConcurrentMap<K, A>>mapMerger(downstream.combiner());
 998         @SuppressWarnings("unchecked")
 999         Supplier<ConcurrentMap<K, A>> mangledFactory = (Supplier<ConcurrentMap<K, A>>) mapFactory;
1000         BiConsumer<ConcurrentMap<K, A>, T> accumulator;
1001         if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) {
1002             accumulator = (m, t) -> {
1003                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1004                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1005                 downstreamAccumulator.accept(resultContainer, t);
1006             };
1007         }
1008         else {
1009             accumulator = (m, t) -> {
1010                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1011                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1012                 synchronized (resultContainer) {
1013                     downstreamAccumulator.accept(resultContainer, t);
1014                 }
1015             };
1016         }
1017 
1018         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1019             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_CONCURRENT_ID);
1020         }
1021         else {
1022             @SuppressWarnings("unchecked")
1023             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
1024             Function<ConcurrentMap<K, A>, M> finisher = intermediate -> {
1025                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
1026                 @SuppressWarnings("unchecked")
1027                 M castResult = (M) intermediate;
1028                 return castResult;
1029             };
1030             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_CONCURRENT_NOID);
1031         }
1032     }
1033 
1034     /**
1035      * Returns a {@code Collector} which partitions the input elements according
1036      * to a {@code Predicate}, and organizes them into a
1037      * {@code Map<Boolean, List<T>>}.
1038      *
1039      * There are no guarantees on the type, mutability,
1040      * serializability, or thread-safety of the {@code Map} returned.
1041      *
1042      * @param <T> the type of the input elements
1043      * @param predicate a predicate used for classifying input elements
1044      * @return a {@code Collector} implementing the partitioning operation
1045      *
1046      * @see #partitioningBy(Predicate, Collector)
1047      */
1048     public static <T>
1049     Collector<T, ?, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate) {
1050         return partitioningBy(predicate, toList());
1051     }
1052 
1053     /**
1054      * Returns a {@code Collector} which partitions the input elements according
1055      * to a {@code Predicate}, reduces the values in each partition according to
1056      * another {@code Collector}, and organizes them into a
1057      * {@code Map<Boolean, D>} whose values are the result of the downstream
1058      * reduction.
1059      *
1060      * <p>There are no guarantees on the type, mutability,
1061      * serializability, or thread-safety of the {@code Map} returned.
1062      *
1063      * @param <T> the type of the input elements
1064      * @param <A> the intermediate accumulation type of the downstream collector
1065      * @param <D> the result type of the downstream reduction
1066      * @param predicate a predicate used for classifying input elements
1067      * @param downstream a {@code Collector} implementing the downstream
1068      *                   reduction
1069      * @return a {@code Collector} implementing the cascaded partitioning
1070      *         operation
1071      *
1072      * @see #partitioningBy(Predicate)
1073      */
1074     public static <T, D, A>
1075     Collector<T, ?, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate,
1076                                                     Collector<? super T, A, D> downstream) {
1077         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1078         BiConsumer<Partition<A>, T> accumulator = (result, t) ->
1079                 downstreamAccumulator.accept(predicate.test(t) ? result.forTrue : result.forFalse, t);
1080         BinaryOperator<A> op = downstream.combiner();
1081         BinaryOperator<Partition<A>> merger = (left, right) ->
1082                 new Partition<>(op.apply(left.forTrue, right.forTrue),
1083                                 op.apply(left.forFalse, right.forFalse));
1084         Supplier<Partition<A>> supplier = () ->
1085                 new Partition<>(downstream.supplier().get(),
1086                                 downstream.supplier().get());
1087         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1088             return new CollectorImpl<>(supplier, accumulator, merger, CH_ID);
1089         }
1090         else {
1091             Function<Partition<A>, Map<Boolean, D>> finisher = par ->
1092                     new Partition<>(downstream.finisher().apply(par.forTrue),
1093                                     downstream.finisher().apply(par.forFalse));
1094             return new CollectorImpl<>(supplier, accumulator, merger, finisher, CH_NOID);
1095         }
1096     }
1097 
1098     /**
1099      * Returns a {@code Collector} that accumulates elements into a
1100      * {@code Map} whose keys and values are the result of applying the provided
1101      * mapping functions to the input elements.
1102      *
1103      * <p>If the mapped keys contains duplicates (according to
1104      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1105      * thrown when the collection operation is performed.  If the mapped keys
1106      * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
1107      * instead.
1108      *
1109      * @apiNote
1110      * It is common for either the key or the value to be the input elements.
1111      * In this case, the utility method
1112      * {@link java.util.function.Function#identity()} may be helpful.
1113      * For example, the following produces a {@code Map} mapping
1114      * students to their grade point average:
1115      * <pre>{@code
1116      *     Map<Student, Double> studentToGPA
1117      *         students.stream().collect(toMap(Functions.identity(),
1118      *                                         student -> computeGPA(student)));
1119      * }</pre>
1120      * And the following produces a {@code Map} mapping a unique identifier to
1121      * students:
1122      * <pre>{@code
1123      *     Map<String, Student> studentIdToStudent
1124      *         students.stream().collect(toMap(Student::getId,
1125      *                                         Functions.identity());
1126      * }</pre>
1127      *
1128      * @implNote
1129      * The returned {@code Collector} is not concurrent.  For parallel stream
1130      * pipelines, the {@code combiner} function operates by merging the keys
1131      * from one map into another, which can be an expensive operation.  If it is
1132      * not required that results are inserted into the {@code Map} in encounter
1133      * order, using {@link #toConcurrentMap(Function, Function)}
1134      * may offer better parallel performance.
1135      *
1136      * @param <T> the type of the input elements
1137      * @param <K> the output type of the key mapping function
1138      * @param <U> the output type of the value mapping function
1139      * @param keyMapper a mapping function to produce keys
1140      * @param valueMapper a mapping function to produce values
1141      * @return a {@code Collector} which collects elements into a {@code Map}
1142      * whose keys and values are the result of applying mapping functions to
1143      * the input elements
1144      *
1145      * @see #toMap(Function, Function, BinaryOperator)
1146      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1147      * @see #toConcurrentMap(Function, Function)
1148      */
1149     public static <T, K, U>
1150     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1151                                     Function<? super T, ? extends U> valueMapper) {
1152         return toMap(keyMapper, valueMapper, throwingMerger(), HashMap::new);
1153     }
1154 
1155     /**
1156      * Returns a {@code Collector} that accumulates elements into a
1157      * {@code Map} whose keys and values are the result of applying the provided
1158      * mapping functions to the input elements.
1159      *
1160      * <p>If the mapped
1161      * keys contains duplicates (according to {@link Object#equals(Object)}),
1162      * the value mapping function is applied to each equal element, and the
1163      * results are merged using the provided merging function.
1164      *
1165      * @apiNote
1166      * There are multiple ways to deal with collisions between multiple elements
1167      * mapping to the same key.  The other forms of {@code toMap} simply use
1168      * a merge function that throws unconditionally, but you can easily write
1169      * more flexible merge policies.  For example, if you have a stream
1170      * of {@code Person}, and you want to produce a "phone book" mapping name to
1171      * address, but it is possible that two persons have the same name, you can
1172      * do as follows to gracefully deals with these collisions, and produce a
1173      * {@code Map} mapping names to a concatenated list of addresses:
1174      * <pre>{@code
1175      *     Map<String, String> phoneBook
1176      *         people.stream().collect(toMap(Person::getName,
1177      *                                       Person::getAddress,
1178      *                                       (s, a) -> s + ", " + a));
1179      * }</pre>
1180      *
1181      * @implNote
1182      * The returned {@code Collector} is not concurrent.  For parallel stream
1183      * pipelines, the {@code combiner} function operates by merging the keys
1184      * from one map into another, which can be an expensive operation.  If it is
1185      * not required that results are merged into the {@code Map} in encounter
1186      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator)}
1187      * may offer better parallel performance.
1188      *
1189      * @param <T> the type of the input elements
1190      * @param <K> the output type of the key mapping function
1191      * @param <U> the output type of the value mapping function
1192      * @param keyMapper a mapping function to produce keys
1193      * @param valueMapper a mapping function to produce values
1194      * @param mergeFunction a merge function, used to resolve collisions between
1195      *                      values associated with the same key, as supplied
1196      *                      to {@link Map#merge(Object, Object, BiFunction)}
1197      * @return a {@code Collector} which collects elements into a {@code Map}
1198      * whose keys are the result of applying a key mapping function to the input
1199      * elements, and whose values are the result of applying a value mapping
1200      * function to all input elements equal to the key and combining them
1201      * using the merge function
1202      *
1203      * @see #toMap(Function, Function)
1204      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1205      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1206      */
1207     public static <T, K, U>
1208     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1209                                     Function<? super T, ? extends U> valueMapper,
1210                                     BinaryOperator<U> mergeFunction) {
1211         return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new);
1212     }
1213 
1214     /**
1215      * Returns a {@code Collector} that accumulates elements into a
1216      * {@code Map} whose keys and values are the result of applying the provided
1217      * mapping functions to the input elements.
1218      *
1219      * <p>If the mapped
1220      * keys contains duplicates (according to {@link Object#equals(Object)}),
1221      * the value mapping function is applied to each equal element, and the
1222      * results are merged using the provided merging function.  The {@code Map}
1223      * is created by a provided supplier function.
1224      *
1225      * @implNote
1226      * The returned {@code Collector} is not concurrent.  For parallel stream
1227      * pipelines, the {@code combiner} function operates by merging the keys
1228      * from one map into another, which can be an expensive operation.  If it is
1229      * not required that results are merged into the {@code Map} in encounter
1230      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator, Supplier)}
1231      * may offer better parallel performance.
1232      *
1233      * @param <T> the type of the input elements
1234      * @param <K> the output type of the key mapping function
1235      * @param <U> the output type of the value mapping function
1236      * @param <M> the type of the resulting {@code Map}
1237      * @param keyMapper a mapping function to produce keys
1238      * @param valueMapper a mapping function to produce values
1239      * @param mergeFunction a merge function, used to resolve collisions between
1240      *                      values associated with the same key, as supplied
1241      *                      to {@link Map#merge(Object, Object, BiFunction)}
1242      * @param mapSupplier a function which returns a new, empty {@code Map} into
1243      *                    which the results will be inserted
1244      * @return a {@code Collector} which collects elements into a {@code Map}
1245      * whose keys are the result of applying a key mapping function to the input
1246      * elements, and whose values are the result of applying a value mapping
1247      * function to all input elements equal to the key and combining them
1248      * using the merge function
1249      *
1250      * @see #toMap(Function, Function)
1251      * @see #toMap(Function, Function, BinaryOperator)
1252      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1253      */
1254     public static <T, K, U, M extends Map<K, U>>
1255     Collector<T, ?, M> toMap(Function<? super T, ? extends K> keyMapper,
1256                                 Function<? super T, ? extends U> valueMapper,
1257                                 BinaryOperator<U> mergeFunction,
1258                                 Supplier<M> mapSupplier) {
1259         BiConsumer<M, T> accumulator
1260                 = (map, element) -> map.merge(keyMapper.apply(element),
1261                                               valueMapper.apply(element), mergeFunction);
1262         return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_ID);
1263     }
1264 
1265     /**
1266      * Returns a concurrent {@code Collector} that accumulates elements into a
1267      * {@code ConcurrentMap} whose keys and values are the result of applying
1268      * the provided mapping functions to the input elements.
1269      *
1270      * <p>If the mapped keys contains duplicates (according to
1271      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1272      * thrown when the collection operation is performed.  If the mapped keys
1273      * may have duplicates, use
1274      * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead.
1275      *
1276      * @apiNote
1277      * It is common for either the key or the value to be the input elements.
1278      * In this case, the utility method
1279      * {@link java.util.function.Function#identity()} may be helpful.
1280      * For example, the following produces a {@code Map} mapping
1281      * students to their grade point average:
1282      * <pre>{@code
1283      *     Map<Student, Double> studentToGPA
1284      *         students.stream().collect(toMap(Functions.identity(),
1285      *                                         student -> computeGPA(student)));
1286      * }</pre>
1287      * And the following produces a {@code Map} mapping a unique identifier to
1288      * students:
1289      * <pre>{@code
1290      *     Map<String, Student> studentIdToStudent
1291      *         students.stream().collect(toConcurrentMap(Student::getId,
1292      *                                                   Functions.identity());
1293      * }</pre>
1294      *
1295      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1296      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1297      *
1298      * @param <T> the type of the input elements
1299      * @param <K> the output type of the key mapping function
1300      * @param <U> the output type of the value mapping function
1301      * @param keyMapper the mapping function to produce keys
1302      * @param valueMapper the mapping function to produce values
1303      * @return a concurrent, unordered {@code Collector} which collects elements into a
1304      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1305      * function to the input elements, and whose values are the result of
1306      * applying a value mapping function to the input elements
1307      *
1308      * @see #toMap(Function, Function)
1309      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1310      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1311      */
1312     public static <T, K, U>
1313     Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1314                                                         Function<? super T, ? extends U> valueMapper) {
1315         return toConcurrentMap(keyMapper, valueMapper, throwingMerger(), ConcurrentHashMap::new);
1316     }
1317 
1318     /**
1319      * Returns a concurrent {@code Collector} that accumulates elements into a
1320      * {@code ConcurrentMap} whose keys and values are the result of applying
1321      * the provided mapping functions to the input elements.
1322      *
1323      * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1324      * the value mapping function is applied to each equal element, and the
1325      * results are merged using the provided merging function.
1326      *
1327      * @apiNote
1328      * There are multiple ways to deal with collisions between multiple elements
1329      * mapping to the same key.  The other forms of {@code toConcurrentMap} simply use
1330      * a merge function that throws unconditionally, but you can easily write
1331      * more flexible merge policies.  For example, if you have a stream
1332      * of {@code Person}, and you want to produce a "phone book" mapping name to
1333      * address, but it is possible that two persons have the same name, you can
1334      * do as follows to gracefully deals with these collisions, and produce a
1335      * {@code Map} mapping names to a concatenated list of addresses:
1336      * <pre>{@code
1337      *     Map<String, String> phoneBook
1338      *         people.stream().collect(toConcurrentMap(Person::getName,
1339      *                                                 Person::getAddress,
1340      *                                                 (s, a) -> s + ", " + a));
1341      * }</pre>
1342      *
1343      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1344      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1345      *
1346      * @param <T> the type of the input elements
1347      * @param <K> the output type of the key mapping function
1348      * @param <U> the output type of the value mapping function
1349      * @param keyMapper a mapping function to produce keys
1350      * @param valueMapper a mapping function to produce values
1351      * @param mergeFunction a merge function, used to resolve collisions between
1352      *                      values associated with the same key, as supplied
1353      *                      to {@link Map#merge(Object, Object, BiFunction)}
1354      * @return a concurrent, unordered {@code Collector} which collects elements into a
1355      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1356      * function to the input elements, and whose values are the result of
1357      * applying a value mapping function to all input elements equal to the key
1358      * and combining them using the merge function
1359      *
1360      * @see #toConcurrentMap(Function, Function)
1361      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1362      * @see #toMap(Function, Function, BinaryOperator)
1363      */
1364     public static <T, K, U>
1365     Collector<T, ?, ConcurrentMap<K,U>>
1366     toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1367                     Function<? super T, ? extends U> valueMapper,
1368                     BinaryOperator<U> mergeFunction) {
1369         return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new);
1370     }
1371 
1372     /**
1373      * Returns a concurrent {@code Collector} that accumulates elements into a
1374      * {@code ConcurrentMap} whose keys and values are the result of applying
1375      * the provided mapping functions to the input elements.
1376      *
1377      * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1378      * the value mapping function is applied to each equal element, and the
1379      * results are merged using the provided merging function.  The
1380      * {@code ConcurrentMap} is created by a provided supplier function.
1381      *
1382      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1383      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1384      *
1385      * @param <T> the type of the input elements
1386      * @param <K> the output type of the key mapping function
1387      * @param <U> the output type of the value mapping function
1388      * @param <M> the type of the resulting {@code ConcurrentMap}
1389      * @param keyMapper a mapping function to produce keys
1390      * @param valueMapper a mapping function to produce values
1391      * @param mergeFunction a merge function, used to resolve collisions between
1392      *                      values associated with the same key, as supplied
1393      *                      to {@link Map#merge(Object, Object, BiFunction)}
1394      * @param mapSupplier a function which returns a new, empty {@code Map} into
1395      *                    which the results will be inserted
1396      * @return a concurrent, unordered {@code Collector} which collects elements into a
1397      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1398      * function to the input elements, and whose values are the result of
1399      * applying a value mapping function to all input elements equal to the key
1400      * and combining them using the merge function
1401      *
1402      * @see #toConcurrentMap(Function, Function)
1403      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1404      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1405      */
1406     public static <T, K, U, M extends ConcurrentMap<K, U>>
1407     Collector<T, ?, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1408                                        Function<? super T, ? extends U> valueMapper,
1409                                        BinaryOperator<U> mergeFunction,
1410                                        Supplier<M> mapSupplier) {
1411         BiConsumer<M, T> accumulator
1412                 = (map, element) -> map.merge(keyMapper.apply(element),
1413                                               valueMapper.apply(element), mergeFunction);
1414         return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_CONCURRENT_ID);
1415     }
1416 
1417     /**
1418      * Returns a {@code Collector} which applies an {@code int}-producing
1419      * mapping function to each input element, and returns summary statistics
1420      * for the resulting values.
1421      *
1422      * @param <T> the type of the input elements
1423      * @param mapper a mapping function to apply to each element
1424      * @return a {@code Collector} implementing the summary-statistics reduction
1425      *
1426      * @see #summarizingDouble(ToDoubleFunction)
1427      * @see #summarizingLong(ToLongFunction)
1428      */
1429     public static <T>
1430     Collector<T, ?, IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper) {
1431         return new CollectorImpl<T, IntSummaryStatistics, IntSummaryStatistics>(
1432                 IntSummaryStatistics::new,
1433                 (r, t) -> r.accept(mapper.applyAsInt(t)),
1434                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1435     }
1436 
1437     /**
1438      * Returns a {@code Collector} which applies an {@code long}-producing
1439      * mapping function to each input element, and returns summary statistics
1440      * for the resulting values.
1441      *
1442      * @param <T> the type of the input elements
1443      * @param mapper the mapping function to apply to each element
1444      * @return a {@code Collector} implementing the summary-statistics reduction
1445      *
1446      * @see #summarizingDouble(ToDoubleFunction)
1447      * @see #summarizingInt(ToIntFunction)
1448      */
1449     public static <T>
1450     Collector<T, ?, LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper) {
1451         return new CollectorImpl<T, LongSummaryStatistics, LongSummaryStatistics>(
1452                 LongSummaryStatistics::new,
1453                 (r, t) -> r.accept(mapper.applyAsLong(t)),
1454                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1455     }
1456 
1457     /**
1458      * Returns a {@code Collector} which applies an {@code double}-producing
1459      * mapping function to each input element, and returns summary statistics
1460      * for the resulting values.
1461      *
1462      * @param <T> the type of the input elements
1463      * @param mapper a mapping function to apply to each element
1464      * @return a {@code Collector} implementing the summary-statistics reduction
1465      *
1466      * @see #summarizingLong(ToLongFunction)
1467      * @see #summarizingInt(ToIntFunction)
1468      */
1469     public static <T>
1470     Collector<T, ?, DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper) {
1471         return new CollectorImpl<T, DoubleSummaryStatistics, DoubleSummaryStatistics>(
1472                 DoubleSummaryStatistics::new,
1473                 (r, t) -> r.accept(mapper.applyAsDouble(t)),
1474                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1475     }
1476 
1477     /**
1478      * Implementation class used by partitioningBy.
1479      */
1480     private static final class Partition<T>
1481             extends AbstractMap<Boolean, T>
1482             implements Map<Boolean, T> {
1483         final T forTrue;
1484         final T forFalse;
1485 
1486         Partition(T forTrue, T forFalse) {
1487             this.forTrue = forTrue;
1488             this.forFalse = forFalse;
1489         }
1490 
1491         @Override
1492         public Set<Map.Entry<Boolean, T>> entrySet() {
1493             return new AbstractSet<Map.Entry<Boolean, T>>() {
1494                 @Override
1495                 public Iterator<Map.Entry<Boolean, T>> iterator() {
1496                     Map.Entry<Boolean, T> falseEntry = new SimpleImmutableEntry<>(false, forFalse);
1497                     Map.Entry<Boolean, T> trueEntry = new SimpleImmutableEntry<>(true, forTrue);
1498                     return Arrays.asList(falseEntry, trueEntry).iterator();
1499                 }
1500 
1501                 @Override
1502                 public int size() {
1503                     return 2;
1504                 }
1505             };
1506         }
1507     }
1508 }