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[2],
 510                 (a, t) -> { sumWithCompensation(a, mapper.applyAsDouble(t)); },
 511                 (a, b) -> { sumWithCompensation(a, b[0]); return sumWithCompensation(a, b[1]); },
 512                 a -> a[0],
 513                 CH_NOID);
 514     }
 515 
 516     /**
 517      * Incorporate a new double value using Kahan summation /
 518      * compensation summation.
 519      *
 520      * High-order bits of the sum are in intermediateSum[0], low-order
 521      * bits of the sum are in intermediateSum[1], any additional
 522      * elements are application-specific.
 523      *
 524      * @param intermediateSum the high-order and low-order words of the intermediate sum
 525      * @param value the name value to be included in the running sum
 526      */
 527     static double[] sumWithCompensation(double[] intermediateSum, double value) {
 528         double tmp = value - intermediateSum[1];
 529         double sum = intermediateSum[0];
 530         double velvel = sum + tmp; // Little wolf of rounding error
 531         intermediateSum[1] = (velvel - sum) - tmp;
 532         intermediateSum[0] = velvel;
 533         return intermediateSum;
 534     }
 535 
 536 
 537     /**
 538      * Returns a {@code Collector} that produces the arithmetic mean of an integer-valued
 539      * function applied to the input elements.  If no elements are present,
 540      * the result is 0.
 541      *
 542      * @param <T> the type of the input elements
 543      * @param mapper a function extracting the property to be summed
 544      * @return a {@code Collector} that produces the sum of a derived property
 545      */
 546     public static <T> Collector<T, ?, Double>
 547     averagingInt(ToIntFunction<? super T> mapper) {
 548         return new CollectorImpl<>(
 549                 () -> new long[2],
 550                 (a, t) -> { a[0] += mapper.applyAsInt(t); a[1]++; },
 551                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
 552                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
 553     }
 554 
 555     /**
 556      * Returns a {@code Collector} that produces the arithmetic mean of a long-valued
 557      * function applied to the input elements.  If no elements are present,
 558      * the result is 0.
 559      *
 560      * @param <T> the type of the input elements
 561      * @param mapper a function extracting the property to be summed
 562      * @return a {@code Collector} that produces the sum of a derived property
 563      */
 564     public static <T> Collector<T, ?, Double>
 565     averagingLong(ToLongFunction<? super T> mapper) {
 566         return new CollectorImpl<>(
 567                 () -> new long[2],
 568                 (a, t) -> { a[0] += mapper.applyAsLong(t); a[1]++; },
 569                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
 570                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
 571     }
 572 
 573     /**
 574      * Returns a {@code Collector} that produces the arithmetic mean of a double-valued
 575      * function applied to the input elements.  If no elements are present,
 576      * the result is 0.
 577      *
 578      * <p>The average returned can vary depending upon the order in which
 579      * values are recorded, due to accumulated rounding error in
 580      * addition of values of differing magnitudes. Values sorted by increasing
 581      * absolute magnitude tend to yield more accurate results.  If any recorded
 582      * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
 583      * average will be {@code NaN}.
 584      *
 585      * @param <T> the type of the input elements
 586      * @param mapper a function extracting the property to be summed
 587      * @return a {@code Collector} that produces the sum of a derived property
 588      */
 589     public static <T> Collector<T, ?, Double>
 590     averagingDouble(ToDoubleFunction<? super T> mapper) {
 591         return new CollectorImpl<>(
 592                 () -> new double[3],
 593                 (a, t) -> { sumWithCompensation(a, mapper.applyAsDouble(t)); a[2]++; },
 594                 (a, b) -> { sumWithCompensation(a, b[0]); sumWithCompensation(a, b[1]); a[2] += b[2]; return a; },
 595                 a -> (a[2] == 0) ? 0.0d : (a[0] / a[2]),
 596                 CH_NOID);
 597     }
 598 
 599     /**
 600      * Returns a {@code Collector} which performs a reduction of its
 601      * input elements under a specified {@code BinaryOperator} using the
 602      * provided identity.
 603      *
 604      * @apiNote
 605      * The {@code reducing()} collectors are most useful when used in a
 606      * multi-level reduction, downstream of {@code groupingBy} or
 607      * {@code partitioningBy}.  To perform a simple reduction on a stream,
 608      * use {@link Stream#reduce(Object, BinaryOperator)}} instead.
 609      *
 610      * @param <T> element type for the input and output of the reduction
 611      * @param identity the identity value for the reduction (also, the value
 612      *                 that is returned when there are no input elements)
 613      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
 614      * @return a {@code Collector} which implements the reduction operation
 615      *
 616      * @see #reducing(BinaryOperator)
 617      * @see #reducing(Object, Function, BinaryOperator)
 618      */
 619     public static <T> Collector<T, ?, T>
 620     reducing(T identity, BinaryOperator<T> op) {
 621         return new CollectorImpl<>(
 622                 boxSupplier(identity),
 623                 (a, t) -> { a[0] = op.apply(a[0], t); },
 624                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
 625                 a -> a[0],
 626                 CH_NOID);
 627     }
 628 
 629     @SuppressWarnings("unchecked")
 630     private static <T> Supplier<T[]> boxSupplier(T identity) {
 631         return () -> (T[]) new Object[] { identity };
 632     }
 633 
 634     /**
 635      * Returns a {@code Collector} which performs a reduction of its
 636      * input elements under a specified {@code BinaryOperator}.  The result
 637      * is described as an {@code Optional<T>}.
 638      *
 639      * @apiNote
 640      * The {@code reducing()} collectors are most useful when used in a
 641      * multi-level reduction, downstream of {@code groupingBy} or
 642      * {@code partitioningBy}.  To perform a simple reduction on a stream,
 643      * use {@link Stream#reduce(BinaryOperator)} instead.
 644      *
 645      * <p>For example, given a stream of {@code Person}, to calculate tallest
 646      * person in each city:
 647      * <pre>{@code
 648      *     Comparator<Person> byHeight = Comparator.comparing(Person::getHeight);
 649      *     Map<City, Person> tallestByCity
 650      *         = people.stream().collect(groupingBy(Person::getCity, reducing(BinaryOperator.maxBy(byHeight))));
 651      * }</pre>
 652      *
 653      * @param <T> element type for the input and output of the reduction
 654      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
 655      * @return a {@code Collector} which implements the reduction operation
 656      *
 657      * @see #reducing(Object, BinaryOperator)
 658      * @see #reducing(Object, Function, BinaryOperator)
 659      */
 660     public static <T> Collector<T, ?, Optional<T>>
 661     reducing(BinaryOperator<T> op) {
 662         class OptionalBox implements Consumer<T> {
 663             T value = null;
 664             boolean present = false;
 665 
 666             @Override
 667             public void accept(T t) {
 668                 if (present) {
 669                     value = op.apply(value, t);
 670                 }
 671                 else {
 672                     value = t;
 673                     present = true;
 674                 }
 675             }
 676         }
 677 
 678         return new CollectorImpl<T, OptionalBox, Optional<T>>(
 679                 OptionalBox::new, OptionalBox::accept,
 680                 (a, b) -> { if (b.present) a.accept(b.value); return a; },
 681                 a -> Optional.ofNullable(a.value), CH_NOID);
 682     }
 683 
 684     /**
 685      * Returns a {@code Collector} which performs a reduction of its
 686      * input elements under a specified mapping function and
 687      * {@code BinaryOperator}. This is a generalization of
 688      * {@link #reducing(Object, BinaryOperator)} which allows a transformation
 689      * of the elements before reduction.
 690      *
 691      * @apiNote
 692      * The {@code reducing()} collectors are most useful when used in a
 693      * multi-level reduction, downstream of {@code groupingBy} or
 694      * {@code partitioningBy}.  To perform a simple map-reduce on a stream,
 695      * use {@link Stream#map(Function)} and {@link Stream#reduce(Object, BinaryOperator)}
 696      * instead.
 697      *
 698      * <p>For example, given a stream of {@code Person}, to calculate the longest
 699      * last name of residents in each city:
 700      * <pre>{@code
 701      *     Comparator<String> byLength = Comparator.comparing(String::length);
 702      *     Map<City, String> longestLastNameByCity
 703      *         = people.stream().collect(groupingBy(Person::getCity,
 704      *                                              reducing(Person::getLastName, BinaryOperator.maxBy(byLength))));
 705      * }</pre>
 706      *
 707      * @param <T> the type of the input elements
 708      * @param <U> the type of the mapped values
 709      * @param identity the identity value for the reduction (also, the value
 710      *                 that is returned when there are no input elements)
 711      * @param mapper a mapping function to apply to each input value
 712      * @param op a {@code BinaryOperator<U>} used to reduce the mapped values
 713      * @return a {@code Collector} implementing the map-reduce operation
 714      *
 715      * @see #reducing(Object, BinaryOperator)
 716      * @see #reducing(BinaryOperator)
 717      */
 718     public static <T, U>
 719     Collector<T, ?, U> reducing(U identity,
 720                                 Function<? super T, ? extends U> mapper,
 721                                 BinaryOperator<U> op) {
 722         return new CollectorImpl<>(
 723                 boxSupplier(identity),
 724                 (a, t) -> { a[0] = op.apply(a[0], mapper.apply(t)); },
 725                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
 726                 a -> a[0], CH_NOID);
 727     }
 728 
 729     /**
 730      * Returns a {@code Collector} implementing a "group by" operation on
 731      * input elements of type {@code T}, grouping elements according to a
 732      * classification function, and returning the results in a {@code Map}.
 733      *
 734      * <p>The classification function maps elements to some key type {@code K}.
 735      * The collector produces a {@code Map<K, List<T>>} whose keys are the
 736      * values resulting from applying the classification function to the input
 737      * elements, and whose corresponding values are {@code List}s containing the
 738      * input elements which map to the associated key under the classification
 739      * function.
 740      *
 741      * <p>There are no guarantees on the type, mutability, serializability, or
 742      * thread-safety of the {@code Map} or {@code List} objects returned.
 743      * @implSpec
 744      * This produces a result similar to:
 745      * <pre>{@code
 746      *     groupingBy(classifier, toList());
 747      * }</pre>
 748      *
 749      * @implNote
 750      * The returned {@code Collector} is not concurrent.  For parallel stream
 751      * pipelines, the {@code combiner} function operates by merging the keys
 752      * from one map into another, which can be an expensive operation.  If
 753      * preservation of the order in which elements appear in the resulting {@code Map}
 754      * collector is not required, using {@link #groupingByConcurrent(Function)}
 755      * may offer better parallel performance.
 756      *
 757      * @param <T> the type of the input elements
 758      * @param <K> the type of the keys
 759      * @param classifier the classifier function mapping input elements to keys
 760      * @return a {@code Collector} implementing the group-by operation
 761      *
 762      * @see #groupingBy(Function, Collector)
 763      * @see #groupingBy(Function, Supplier, Collector)
 764      * @see #groupingByConcurrent(Function)
 765      */
 766     public static <T, K> Collector<T, ?, Map<K, List<T>>>
 767     groupingBy(Function<? super T, ? extends K> classifier) {
 768         return groupingBy(classifier, toList());
 769     }
 770 
 771     /**
 772      * Returns a {@code Collector} implementing a cascaded "group by" operation
 773      * on input elements of type {@code T}, grouping elements according to a
 774      * classification function, and then performing a reduction operation on
 775      * the values associated with a given key using the specified downstream
 776      * {@code Collector}.
 777      *
 778      * <p>The classification function maps elements to some key type {@code K}.
 779      * The downstream collector operates on elements of type {@code T} and
 780      * produces a result of type {@code D}. The resulting collector produces a
 781      * {@code Map<K, D>}.
 782      *
 783      * <p>There are no guarantees on the type, mutability,
 784      * serializability, or thread-safety of the {@code Map} returned.
 785      *
 786      * <p>For example, to compute the set of last names of people in each city:
 787      * <pre>{@code
 788      *     Map<City, Set<String>> namesByCity
 789      *         = people.stream().collect(groupingBy(Person::getCity,
 790      *                                              mapping(Person::getLastName, toSet())));
 791      * }</pre>
 792      *
 793      * @implNote
 794      * The returned {@code Collector} is not concurrent.  For parallel stream
 795      * pipelines, the {@code combiner} function operates by merging the keys
 796      * from one map into another, which can be an expensive operation.  If
 797      * preservation of the order in which elements are presented to the downstream
 798      * collector is not required, using {@link #groupingByConcurrent(Function, Collector)}
 799      * may offer better parallel performance.
 800      *
 801      * @param <T> the type of the input elements
 802      * @param <K> the type of the keys
 803      * @param <A> the intermediate accumulation type of the downstream collector
 804      * @param <D> the result type of the downstream reduction
 805      * @param classifier a classifier function mapping input elements to keys
 806      * @param downstream a {@code Collector} implementing the downstream reduction
 807      * @return a {@code Collector} implementing the cascaded group-by operation
 808      * @see #groupingBy(Function)
 809      *
 810      * @see #groupingBy(Function, Supplier, Collector)
 811      * @see #groupingByConcurrent(Function, Collector)
 812      */
 813     public static <T, K, A, D>
 814     Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,
 815                                           Collector<? super T, A, D> downstream) {
 816         return groupingBy(classifier, HashMap::new, downstream);
 817     }
 818 
 819     /**
 820      * Returns a {@code Collector} implementing a cascaded "group by" operation
 821      * on input elements of type {@code T}, grouping elements according to a
 822      * classification function, and then performing a reduction operation on
 823      * the values associated with a given key using the specified downstream
 824      * {@code Collector}.  The {@code Map} produced by the Collector is created
 825      * with the supplied factory function.
 826      *
 827      * <p>The classification function maps elements to some key type {@code K}.
 828      * The downstream collector operates on elements of type {@code T} and
 829      * produces a result of type {@code D}. The resulting collector produces a
 830      * {@code Map<K, D>}.
 831      *
 832      * <p>For example, to compute the set of last names of people in each city,
 833      * where the city names are sorted:
 834      * <pre>{@code
 835      *     Map<City, Set<String>> namesByCity
 836      *         = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
 837      *                                              mapping(Person::getLastName, toSet())));
 838      * }</pre>
 839      *
 840      * @implNote
 841      * The returned {@code Collector} is not concurrent.  For parallel stream
 842      * pipelines, the {@code combiner} function operates by merging the keys
 843      * from one map into another, which can be an expensive operation.  If
 844      * preservation of the order in which elements are presented to the downstream
 845      * collector is not required, using {@link #groupingByConcurrent(Function, Supplier, Collector)}
 846      * may offer better parallel performance.
 847      *
 848      * @param <T> the type of the input elements
 849      * @param <K> the type of the keys
 850      * @param <A> the intermediate accumulation type of the downstream collector
 851      * @param <D> the result type of the downstream reduction
 852      * @param <M> the type of the resulting {@code Map}
 853      * @param classifier a classifier function mapping input elements to keys
 854      * @param downstream a {@code Collector} implementing the downstream reduction
 855      * @param mapFactory a function which, when called, produces a new empty
 856      *                   {@code Map} of the desired type
 857      * @return a {@code Collector} implementing the cascaded group-by operation
 858      *
 859      * @see #groupingBy(Function, Collector)
 860      * @see #groupingBy(Function)
 861      * @see #groupingByConcurrent(Function, Supplier, Collector)
 862      */
 863     public static <T, K, D, A, M extends Map<K, D>>
 864     Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier,
 865                                   Supplier<M> mapFactory,
 866                                   Collector<? super T, A, D> downstream) {
 867         Supplier<A> downstreamSupplier = downstream.supplier();
 868         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
 869         BiConsumer<Map<K, A>, T> accumulator = (m, t) -> {
 870             K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
 871             A container = m.computeIfAbsent(key, k -> downstreamSupplier.get());
 872             downstreamAccumulator.accept(container, t);
 873         };
 874         BinaryOperator<Map<K, A>> merger = Collectors.<K, A, Map<K, A>>mapMerger(downstream.combiner());
 875         @SuppressWarnings("unchecked")
 876         Supplier<Map<K, A>> mangledFactory = (Supplier<Map<K, A>>) mapFactory;
 877 
 878         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
 879             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_ID);
 880         }
 881         else {
 882             @SuppressWarnings("unchecked")
 883             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
 884             Function<Map<K, A>, M> finisher = intermediate -> {
 885                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
 886                 @SuppressWarnings("unchecked")
 887                 M castResult = (M) intermediate;
 888                 return castResult;
 889             };
 890             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_NOID);
 891         }
 892     }
 893 
 894     /**
 895      * Returns a concurrent {@code Collector} implementing a "group by"
 896      * operation on input elements of type {@code T}, grouping elements
 897      * according to a classification function.
 898      *
 899      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 900      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 901      *
 902      * <p>The classification function maps elements to some key type {@code K}.
 903      * The collector produces a {@code ConcurrentMap<K, List<T>>} whose keys are the
 904      * values resulting from applying the classification function to the input
 905      * elements, and whose corresponding values are {@code List}s containing the
 906      * input elements which map to the associated key under the classification
 907      * function.
 908      *
 909      * <p>There are no guarantees on the type, mutability, or serializability
 910      * of the {@code Map} or {@code List} objects returned, or of the
 911      * thread-safety of the {@code List} objects returned.
 912      * @implSpec
 913      * This produces a result similar to:
 914      * <pre>{@code
 915      *     groupingByConcurrent(classifier, toList());
 916      * }</pre>
 917      *
 918      * @param <T> the type of the input elements
 919      * @param <K> the type of the keys
 920      * @param classifier a classifier function mapping input elements to keys
 921      * @return a concurrent, unordered {@code Collector} implementing the group-by operation
 922      *
 923      * @see #groupingBy(Function)
 924      * @see #groupingByConcurrent(Function, Collector)
 925      * @see #groupingByConcurrent(Function, Supplier, Collector)
 926      */
 927     public static <T, K>
 928     Collector<T, ?, ConcurrentMap<K, List<T>>>
 929     groupingByConcurrent(Function<? super T, ? extends K> classifier) {
 930         return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList());
 931     }
 932 
 933     /**
 934      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
 935      * operation on input elements of type {@code T}, grouping elements
 936      * according to a classification function, and then performing a reduction
 937      * operation on the values associated with a given key using the specified
 938      * downstream {@code Collector}.
 939      *
 940      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 941      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 942      *
 943      * <p>The classification function maps elements to some key type {@code K}.
 944      * The downstream collector operates on elements of type {@code T} and
 945      * produces a result of type {@code D}. The resulting collector produces a
 946      * {@code Map<K, D>}.
 947      *
 948      * <p>For example, to compute the set of last names of people in each city,
 949      * where the city names are sorted:
 950      * <pre>{@code
 951      *     ConcurrentMap<City, Set<String>> namesByCity
 952      *         = people.stream().collect(groupingByConcurrent(Person::getCity,
 953      *                                                        mapping(Person::getLastName, toSet())));
 954      * }</pre>
 955      *
 956      * @param <T> the type of the input elements
 957      * @param <K> the type of the keys
 958      * @param <A> the intermediate accumulation type of the downstream collector
 959      * @param <D> the result type of the downstream reduction
 960      * @param classifier a classifier function mapping input elements to keys
 961      * @param downstream a {@code Collector} implementing the downstream reduction
 962      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
 963      *
 964      * @see #groupingBy(Function, Collector)
 965      * @see #groupingByConcurrent(Function)
 966      * @see #groupingByConcurrent(Function, Supplier, Collector)
 967      */
 968     public static <T, K, A, D>
 969     Collector<T, ?, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier,
 970                                                               Collector<? super T, A, D> downstream) {
 971         return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream);
 972     }
 973 
 974     /**
 975      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
 976      * operation on input elements of type {@code T}, grouping elements
 977      * according to a classification function, and then performing a reduction
 978      * operation on the values associated with a given key using the specified
 979      * downstream {@code Collector}.  The {@code ConcurrentMap} produced by the
 980      * Collector is created with the supplied factory function.
 981      *
 982      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
 983      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
 984      *
 985      * <p>The classification function maps elements to some key type {@code K}.
 986      * The downstream collector operates on elements of type {@code T} and
 987      * produces a result of type {@code D}. The resulting collector produces a
 988      * {@code Map<K, D>}.
 989      *
 990      * <p>For example, to compute the set of last names of people in each city,
 991      * where the city names are sorted:
 992      * <pre>{@code
 993      *     ConcurrentMap<City, Set<String>> namesByCity
 994      *         = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
 995      *                                              mapping(Person::getLastName, toSet())));
 996      * }</pre>
 997      *
 998      *
 999      * @param <T> the type of the input elements
1000      * @param <K> the type of the keys
1001      * @param <A> the intermediate accumulation type of the downstream collector
1002      * @param <D> the result type of the downstream reduction
1003      * @param <M> the type of the resulting {@code ConcurrentMap}
1004      * @param classifier a classifier function mapping input elements to keys
1005      * @param downstream a {@code Collector} implementing the downstream reduction
1006      * @param mapFactory a function which, when called, produces a new empty
1007      *                   {@code ConcurrentMap} of the desired type
1008      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
1009      *
1010      * @see #groupingByConcurrent(Function)
1011      * @see #groupingByConcurrent(Function, Collector)
1012      * @see #groupingBy(Function, Supplier, Collector)
1013      */
1014     public static <T, K, A, D, M extends ConcurrentMap<K, D>>
1015     Collector<T, ?, M> groupingByConcurrent(Function<? super T, ? extends K> classifier,
1016                                             Supplier<M> mapFactory,
1017                                             Collector<? super T, A, D> downstream) {
1018         Supplier<A> downstreamSupplier = downstream.supplier();
1019         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1020         BinaryOperator<ConcurrentMap<K, A>> merger = Collectors.<K, A, ConcurrentMap<K, A>>mapMerger(downstream.combiner());
1021         @SuppressWarnings("unchecked")
1022         Supplier<ConcurrentMap<K, A>> mangledFactory = (Supplier<ConcurrentMap<K, A>>) mapFactory;
1023         BiConsumer<ConcurrentMap<K, A>, T> accumulator;
1024         if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) {
1025             accumulator = (m, t) -> {
1026                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1027                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1028                 downstreamAccumulator.accept(resultContainer, t);
1029             };
1030         }
1031         else {
1032             accumulator = (m, t) -> {
1033                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
1034                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
1035                 synchronized (resultContainer) {
1036                     downstreamAccumulator.accept(resultContainer, t);
1037                 }
1038             };
1039         }
1040 
1041         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1042             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_CONCURRENT_ID);
1043         }
1044         else {
1045             @SuppressWarnings("unchecked")
1046             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
1047             Function<ConcurrentMap<K, A>, M> finisher = intermediate -> {
1048                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
1049                 @SuppressWarnings("unchecked")
1050                 M castResult = (M) intermediate;
1051                 return castResult;
1052             };
1053             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_CONCURRENT_NOID);
1054         }
1055     }
1056 
1057     /**
1058      * Returns a {@code Collector} which partitions the input elements according
1059      * to a {@code Predicate}, and organizes them into a
1060      * {@code Map<Boolean, List<T>>}.
1061      *
1062      * There are no guarantees on the type, mutability,
1063      * serializability, or thread-safety of the {@code Map} returned.
1064      *
1065      * @param <T> the type of the input elements
1066      * @param predicate a predicate used for classifying input elements
1067      * @return a {@code Collector} implementing the partitioning operation
1068      *
1069      * @see #partitioningBy(Predicate, Collector)
1070      */
1071     public static <T>
1072     Collector<T, ?, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate) {
1073         return partitioningBy(predicate, toList());
1074     }
1075 
1076     /**
1077      * Returns a {@code Collector} which partitions the input elements according
1078      * to a {@code Predicate}, reduces the values in each partition according to
1079      * another {@code Collector}, and organizes them into a
1080      * {@code Map<Boolean, D>} whose values are the result of the downstream
1081      * reduction.
1082      *
1083      * <p>There are no guarantees on the type, mutability,
1084      * serializability, or thread-safety of the {@code Map} returned.
1085      *
1086      * @param <T> the type of the input elements
1087      * @param <A> the intermediate accumulation type of the downstream collector
1088      * @param <D> the result type of the downstream reduction
1089      * @param predicate a predicate used for classifying input elements
1090      * @param downstream a {@code Collector} implementing the downstream
1091      *                   reduction
1092      * @return a {@code Collector} implementing the cascaded partitioning
1093      *         operation
1094      *
1095      * @see #partitioningBy(Predicate)
1096      */
1097     public static <T, D, A>
1098     Collector<T, ?, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate,
1099                                                     Collector<? super T, A, D> downstream) {
1100         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
1101         BiConsumer<Partition<A>, T> accumulator = (result, t) ->
1102                 downstreamAccumulator.accept(predicate.test(t) ? result.forTrue : result.forFalse, t);
1103         BinaryOperator<A> op = downstream.combiner();
1104         BinaryOperator<Partition<A>> merger = (left, right) ->
1105                 new Partition<>(op.apply(left.forTrue, right.forTrue),
1106                                 op.apply(left.forFalse, right.forFalse));
1107         Supplier<Partition<A>> supplier = () ->
1108                 new Partition<>(downstream.supplier().get(),
1109                                 downstream.supplier().get());
1110         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
1111             return new CollectorImpl<>(supplier, accumulator, merger, CH_ID);
1112         }
1113         else {
1114             Function<Partition<A>, Map<Boolean, D>> finisher = par ->
1115                     new Partition<>(downstream.finisher().apply(par.forTrue),
1116                                     downstream.finisher().apply(par.forFalse));
1117             return new CollectorImpl<>(supplier, accumulator, merger, finisher, CH_NOID);
1118         }
1119     }
1120 
1121     /**
1122      * Returns a {@code Collector} that accumulates elements into a
1123      * {@code Map} whose keys and values are the result of applying the provided
1124      * mapping functions to the input elements.
1125      *
1126      * <p>If the mapped keys contains duplicates (according to
1127      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1128      * thrown when the collection operation is performed.  If the mapped keys
1129      * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
1130      * instead.
1131      *
1132      * @apiNote
1133      * It is common for either the key or the value to be the input elements.
1134      * In this case, the utility method
1135      * {@link java.util.function.Function#identity()} may be helpful.
1136      * For example, the following produces a {@code Map} mapping
1137      * students to their grade point average:
1138      * <pre>{@code
1139      *     Map<Student, Double> studentToGPA
1140      *         students.stream().collect(toMap(Functions.identity(),
1141      *                                         student -> computeGPA(student)));
1142      * }</pre>
1143      * And the following produces a {@code Map} mapping a unique identifier to
1144      * students:
1145      * <pre>{@code
1146      *     Map<String, Student> studentIdToStudent
1147      *         students.stream().collect(toMap(Student::getId,
1148      *                                         Functions.identity());
1149      * }</pre>
1150      *
1151      * @implNote
1152      * The returned {@code Collector} is not concurrent.  For parallel stream
1153      * pipelines, the {@code combiner} function operates by merging the keys
1154      * from one map into another, which can be an expensive operation.  If it is
1155      * not required that results are inserted into the {@code Map} in encounter
1156      * order, using {@link #toConcurrentMap(Function, Function)}
1157      * may offer better parallel performance.
1158      *
1159      * @param <T> the type of the input elements
1160      * @param <K> the output type of the key mapping function
1161      * @param <U> the output type of the value mapping function
1162      * @param keyMapper a mapping function to produce keys
1163      * @param valueMapper a mapping function to produce values
1164      * @return a {@code Collector} which collects elements into a {@code Map}
1165      * whose keys and values are the result of applying mapping functions to
1166      * the input elements
1167      *
1168      * @see #toMap(Function, Function, BinaryOperator)
1169      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1170      * @see #toConcurrentMap(Function, Function)
1171      */
1172     public static <T, K, U>
1173     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1174                                     Function<? super T, ? extends U> valueMapper) {
1175         return toMap(keyMapper, valueMapper, throwingMerger(), HashMap::new);
1176     }
1177 
1178     /**
1179      * Returns a {@code Collector} that accumulates elements into a
1180      * {@code Map} whose keys and values are the result of applying the provided
1181      * mapping functions to the input elements.
1182      *
1183      * <p>If the mapped
1184      * keys contains duplicates (according to {@link Object#equals(Object)}),
1185      * the value mapping function is applied to each equal element, and the
1186      * results are merged using the provided merging function.
1187      *
1188      * @apiNote
1189      * There are multiple ways to deal with collisions between multiple elements
1190      * mapping to the same key.  The other forms of {@code toMap} simply use
1191      * a merge function that throws unconditionally, but you can easily write
1192      * more flexible merge policies.  For example, if you have a stream
1193      * of {@code Person}, and you want to produce a "phone book" mapping name to
1194      * address, but it is possible that two persons have the same name, you can
1195      * do as follows to gracefully deals with these collisions, and produce a
1196      * {@code Map} mapping names to a concatenated list of addresses:
1197      * <pre>{@code
1198      *     Map<String, String> phoneBook
1199      *         people.stream().collect(toMap(Person::getName,
1200      *                                       Person::getAddress,
1201      *                                       (s, a) -> s + ", " + a));
1202      * }</pre>
1203      *
1204      * @implNote
1205      * The returned {@code Collector} is not concurrent.  For parallel stream
1206      * pipelines, the {@code combiner} function operates by merging the keys
1207      * from one map into another, which can be an expensive operation.  If it is
1208      * not required that results are merged into the {@code Map} in encounter
1209      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator)}
1210      * may offer better parallel performance.
1211      *
1212      * @param <T> the type of the input elements
1213      * @param <K> the output type of the key mapping function
1214      * @param <U> the output type of the value mapping function
1215      * @param keyMapper a mapping function to produce keys
1216      * @param valueMapper a mapping function to produce values
1217      * @param mergeFunction a merge function, used to resolve collisions between
1218      *                      values associated with the same key, as supplied
1219      *                      to {@link Map#merge(Object, Object, BiFunction)}
1220      * @return a {@code Collector} which collects elements into a {@code Map}
1221      * whose keys are the result of applying a key mapping function to the input
1222      * elements, and whose values are the result of applying a value mapping
1223      * function to all input elements equal to the key and combining them
1224      * using the merge function
1225      *
1226      * @see #toMap(Function, Function)
1227      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1228      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1229      */
1230     public static <T, K, U>
1231     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
1232                                     Function<? super T, ? extends U> valueMapper,
1233                                     BinaryOperator<U> mergeFunction) {
1234         return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new);
1235     }
1236 
1237     /**
1238      * Returns a {@code Collector} that accumulates elements into a
1239      * {@code Map} whose keys and values are the result of applying the provided
1240      * mapping functions to the input elements.
1241      *
1242      * <p>If the mapped
1243      * keys contains duplicates (according to {@link Object#equals(Object)}),
1244      * the value mapping function is applied to each equal element, and the
1245      * results are merged using the provided merging function.  The {@code Map}
1246      * is created by a provided supplier function.
1247      *
1248      * @implNote
1249      * The returned {@code Collector} is not concurrent.  For parallel stream
1250      * pipelines, the {@code combiner} function operates by merging the keys
1251      * from one map into another, which can be an expensive operation.  If it is
1252      * not required that results are merged into the {@code Map} in encounter
1253      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator, Supplier)}
1254      * may offer better parallel performance.
1255      *
1256      * @param <T> the type of the input elements
1257      * @param <K> the output type of the key mapping function
1258      * @param <U> the output type of the value mapping function
1259      * @param <M> the type of the resulting {@code Map}
1260      * @param keyMapper a mapping function to produce keys
1261      * @param valueMapper a mapping function to produce values
1262      * @param mergeFunction a merge function, used to resolve collisions between
1263      *                      values associated with the same key, as supplied
1264      *                      to {@link Map#merge(Object, Object, BiFunction)}
1265      * @param mapSupplier a function which returns a new, empty {@code Map} into
1266      *                    which the results will be inserted
1267      * @return a {@code Collector} which collects elements into a {@code Map}
1268      * whose keys are the result of applying a key mapping function to the input
1269      * elements, and whose values are the result of applying a value mapping
1270      * function to all input elements equal to the key and combining them
1271      * using the merge function
1272      *
1273      * @see #toMap(Function, Function)
1274      * @see #toMap(Function, Function, BinaryOperator)
1275      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1276      */
1277     public static <T, K, U, M extends Map<K, U>>
1278     Collector<T, ?, M> toMap(Function<? super T, ? extends K> keyMapper,
1279                                 Function<? super T, ? extends U> valueMapper,
1280                                 BinaryOperator<U> mergeFunction,
1281                                 Supplier<M> mapSupplier) {
1282         BiConsumer<M, T> accumulator
1283                 = (map, element) -> map.merge(keyMapper.apply(element),
1284                                               valueMapper.apply(element), mergeFunction);
1285         return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_ID);
1286     }
1287 
1288     /**
1289      * Returns a concurrent {@code Collector} that accumulates elements into a
1290      * {@code ConcurrentMap} whose keys and values are the result of applying
1291      * the provided mapping functions to the input elements.
1292      *
1293      * <p>If the mapped keys contains duplicates (according to
1294      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
1295      * thrown when the collection operation is performed.  If the mapped keys
1296      * may have duplicates, use
1297      * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead.
1298      *
1299      * @apiNote
1300      * It is common for either the key or the value to be the input elements.
1301      * In this case, the utility method
1302      * {@link java.util.function.Function#identity()} may be helpful.
1303      * For example, the following produces a {@code Map} mapping
1304      * students to their grade point average:
1305      * <pre>{@code
1306      *     Map<Student, Double> studentToGPA
1307      *         students.stream().collect(toMap(Functions.identity(),
1308      *                                         student -> computeGPA(student)));
1309      * }</pre>
1310      * And the following produces a {@code Map} mapping a unique identifier to
1311      * students:
1312      * <pre>{@code
1313      *     Map<String, Student> studentIdToStudent
1314      *         students.stream().collect(toConcurrentMap(Student::getId,
1315      *                                                   Functions.identity());
1316      * }</pre>
1317      *
1318      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1319      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1320      *
1321      * @param <T> the type of the input elements
1322      * @param <K> the output type of the key mapping function
1323      * @param <U> the output type of the value mapping function
1324      * @param keyMapper the mapping function to produce keys
1325      * @param valueMapper the mapping function to produce values
1326      * @return a concurrent, unordered {@code Collector} which collects elements into a
1327      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1328      * function to the input elements, and whose values are the result of
1329      * applying a value mapping function to the input elements
1330      *
1331      * @see #toMap(Function, Function)
1332      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1333      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1334      */
1335     public static <T, K, U>
1336     Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1337                                                         Function<? super T, ? extends U> valueMapper) {
1338         return toConcurrentMap(keyMapper, valueMapper, throwingMerger(), ConcurrentHashMap::new);
1339     }
1340 
1341     /**
1342      * Returns a concurrent {@code Collector} that accumulates elements into a
1343      * {@code ConcurrentMap} whose keys and values are the result of applying
1344      * the provided mapping functions to the input elements.
1345      *
1346      * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1347      * the value mapping function is applied to each equal element, and the
1348      * results are merged using the provided merging function.
1349      *
1350      * @apiNote
1351      * There are multiple ways to deal with collisions between multiple elements
1352      * mapping to the same key.  The other forms of {@code toConcurrentMap} simply use
1353      * a merge function that throws unconditionally, but you can easily write
1354      * more flexible merge policies.  For example, if you have a stream
1355      * of {@code Person}, and you want to produce a "phone book" mapping name to
1356      * address, but it is possible that two persons have the same name, you can
1357      * do as follows to gracefully deals with these collisions, and produce a
1358      * {@code Map} mapping names to a concatenated list of addresses:
1359      * <pre>{@code
1360      *     Map<String, String> phoneBook
1361      *         people.stream().collect(toConcurrentMap(Person::getName,
1362      *                                                 Person::getAddress,
1363      *                                                 (s, a) -> s + ", " + a));
1364      * }</pre>
1365      *
1366      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1367      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1368      *
1369      * @param <T> the type of the input elements
1370      * @param <K> the output type of the key mapping function
1371      * @param <U> the output type of the value mapping function
1372      * @param keyMapper a mapping function to produce keys
1373      * @param valueMapper a mapping function to produce values
1374      * @param mergeFunction a merge function, used to resolve collisions between
1375      *                      values associated with the same key, as supplied
1376      *                      to {@link Map#merge(Object, Object, BiFunction)}
1377      * @return a concurrent, unordered {@code Collector} which collects elements into a
1378      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1379      * function to the input elements, and whose values are the result of
1380      * applying a value mapping function to all input elements equal to the key
1381      * and combining them using the merge function
1382      *
1383      * @see #toConcurrentMap(Function, Function)
1384      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
1385      * @see #toMap(Function, Function, BinaryOperator)
1386      */
1387     public static <T, K, U>
1388     Collector<T, ?, ConcurrentMap<K,U>>
1389     toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1390                     Function<? super T, ? extends U> valueMapper,
1391                     BinaryOperator<U> mergeFunction) {
1392         return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new);
1393     }
1394 
1395     /**
1396      * Returns a concurrent {@code Collector} that accumulates elements into a
1397      * {@code ConcurrentMap} whose keys and values are the result of applying
1398      * the provided mapping functions to the input elements.
1399      *
1400      * <p>If the mapped keys contains duplicates (according to {@link Object#equals(Object)}),
1401      * the value mapping function is applied to each equal element, and the
1402      * results are merged using the provided merging function.  The
1403      * {@code ConcurrentMap} is created by a provided supplier function.
1404      *
1405      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
1406      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
1407      *
1408      * @param <T> the type of the input elements
1409      * @param <K> the output type of the key mapping function
1410      * @param <U> the output type of the value mapping function
1411      * @param <M> the type of the resulting {@code ConcurrentMap}
1412      * @param keyMapper a mapping function to produce keys
1413      * @param valueMapper a mapping function to produce values
1414      * @param mergeFunction a merge function, used to resolve collisions between
1415      *                      values associated with the same key, as supplied
1416      *                      to {@link Map#merge(Object, Object, BiFunction)}
1417      * @param mapSupplier a function which returns a new, empty {@code Map} into
1418      *                    which the results will be inserted
1419      * @return a concurrent, unordered {@code Collector} which collects elements into a
1420      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
1421      * function to the input elements, and whose values are the result of
1422      * applying a value mapping function to all input elements equal to the key
1423      * and combining them using the merge function
1424      *
1425      * @see #toConcurrentMap(Function, Function)
1426      * @see #toConcurrentMap(Function, Function, BinaryOperator)
1427      * @see #toMap(Function, Function, BinaryOperator, Supplier)
1428      */
1429     public static <T, K, U, M extends ConcurrentMap<K, U>>
1430     Collector<T, ?, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
1431                                        Function<? super T, ? extends U> valueMapper,
1432                                        BinaryOperator<U> mergeFunction,
1433                                        Supplier<M> mapSupplier) {
1434         BiConsumer<M, T> accumulator
1435                 = (map, element) -> map.merge(keyMapper.apply(element),
1436                                               valueMapper.apply(element), mergeFunction);
1437         return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_CONCURRENT_ID);
1438     }
1439 
1440     /**
1441      * Returns a {@code Collector} which applies an {@code int}-producing
1442      * mapping function to each input element, and returns summary statistics
1443      * for the resulting values.
1444      *
1445      * @param <T> the type of the input elements
1446      * @param mapper a mapping function to apply to each element
1447      * @return a {@code Collector} implementing the summary-statistics reduction
1448      *
1449      * @see #summarizingDouble(ToDoubleFunction)
1450      * @see #summarizingLong(ToLongFunction)
1451      */
1452     public static <T>
1453     Collector<T, ?, IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper) {
1454         return new CollectorImpl<T, IntSummaryStatistics, IntSummaryStatistics>(
1455                 IntSummaryStatistics::new,
1456                 (r, t) -> r.accept(mapper.applyAsInt(t)),
1457                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1458     }
1459 
1460     /**
1461      * Returns a {@code Collector} which applies an {@code long}-producing
1462      * mapping function to each input element, and returns summary statistics
1463      * for the resulting values.
1464      *
1465      * @param <T> the type of the input elements
1466      * @param mapper the mapping function to apply to each element
1467      * @return a {@code Collector} implementing the summary-statistics reduction
1468      *
1469      * @see #summarizingDouble(ToDoubleFunction)
1470      * @see #summarizingInt(ToIntFunction)
1471      */
1472     public static <T>
1473     Collector<T, ?, LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper) {
1474         return new CollectorImpl<T, LongSummaryStatistics, LongSummaryStatistics>(
1475                 LongSummaryStatistics::new,
1476                 (r, t) -> r.accept(mapper.applyAsLong(t)),
1477                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1478     }
1479 
1480     /**
1481      * Returns a {@code Collector} which applies an {@code double}-producing
1482      * mapping function to each input element, and returns summary statistics
1483      * for the resulting values.
1484      *
1485      * @param <T> the type of the input elements
1486      * @param mapper a mapping function to apply to each element
1487      * @return a {@code Collector} implementing the summary-statistics reduction
1488      *
1489      * @see #summarizingLong(ToLongFunction)
1490      * @see #summarizingInt(ToIntFunction)
1491      */
1492     public static <T>
1493     Collector<T, ?, DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper) {
1494         return new CollectorImpl<T, DoubleSummaryStatistics, DoubleSummaryStatistics>(
1495                 DoubleSummaryStatistics::new,
1496                 (r, t) -> r.accept(mapper.applyAsDouble(t)),
1497                 (l, r) -> { l.combine(r); return l; }, CH_ID);
1498     }
1499 
1500     /**
1501      * Implementation class used by partitioningBy.
1502      */
1503     private static final class Partition<T>
1504             extends AbstractMap<Boolean, T>
1505             implements Map<Boolean, T> {
1506         final T forTrue;
1507         final T forFalse;
1508 
1509         Partition(T forTrue, T forFalse) {
1510             this.forTrue = forTrue;
1511             this.forFalse = forFalse;
1512         }
1513 
1514         @Override
1515         public Set<Map.Entry<Boolean, T>> entrySet() {
1516             return new AbstractSet<Map.Entry<Boolean, T>>() {
1517                 @Override
1518                 public Iterator<Map.Entry<Boolean, T>> iterator() {
1519                     Map.Entry<Boolean, T> falseEntry = new SimpleImmutableEntry<>(false, forFalse);
1520                     Map.Entry<Boolean, T> trueEntry = new SimpleImmutableEntry<>(true, forTrue);
1521                     return Arrays.asList(falseEntry, trueEntry).iterator();
1522                 }
1523 
1524                 @Override
1525                 public int size() {
1526                     return 2;
1527                 }
1528             };
1529         }
1530     }
1531 }
--- EOF ---