       1 /*
       2  * Copyright (c) 2012, 2016, 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.Collection;
      31 import java.util.Collections;
      32 import java.util.Comparator;
      33 import java.util.DoubleSummaryStatistics;
      34 import java.util.EnumSet;
      35 import java.util.HashMap;
      36 import java.util.HashSet;
      37 import java.util.IntSummaryStatistics;
      38 import java.util.Iterator;
      39 import java.util.List;
      40 import java.util.LongSummaryStatistics;
      41 import java.util.Map;
      42 import java.util.Objects;
      43 import java.util.Optional;
      44 import java.util.Set;
      45 import java.util.StringJoiner;
      46 import java.util.concurrent.ConcurrentHashMap;
      47 import java.util.concurrent.ConcurrentMap;
      48 import java.util.function.BiConsumer;
      49 import java.util.function.BiFunction;
      50 import java.util.function.BinaryOperator;
      51 import java.util.function.Consumer;
      52 import java.util.function.Function;
      53 import java.util.function.Predicate;
      54 import java.util.function.Supplier;
      55 import java.util.function.ToDoubleFunction;
      56 import java.util.function.ToIntFunction;
      57 import java.util.function.ToLongFunction;
      58
      59 /**
      60  * Implementations of {@link Collector} that implement various useful reduction
      61  * operations, such as accumulating elements into collections, summarizing
      62  * elements according to various criteria, etc.
      63  *
      64  * <p>The following are examples of using the predefined collectors to perform
      65  * common mutable reduction tasks:
      66  *
      67  * <pre>{@code
      68  * // Accumulate names into a List
      69  * List<String> list = people.stream()
      70  *   .map(Person::getName)
      71  *   .collect(Collectors.toList());
      72  *
      73  * // Accumulate names into a TreeSet
      74  * Set<String> set = people.stream()
      75  *   .map(Person::getName)
      76  *   .collect(Collectors.toCollection(TreeSet::new));
      77  *
      78  * // Convert elements to strings and concatenate them, separated by commas
      79  * String joined = things.stream()
      80  *   .map(Object::toString)
      81  *   .collect(Collectors.joining(", "));
      82  *
      83  * // Compute sum of salaries of employee
      84  * int total = employees.stream()
      85  *   .collect(Collectors.summingInt(Employee::getSalary));
      86  *
      87  * // Group employees by department
      88  * Map<Department, List<Employee>> byDept = employees.stream()
      89  *   .collect(Collectors.groupingBy(Employee::getDepartment));
      90  *
      91  * // Compute sum of salaries by department
      92  * Map<Department, Integer> totalByDept = employees.stream()
      93  *   .collect(Collectors.groupingBy(Employee::getDepartment,
      94  *                                  Collectors.summingInt(Employee::getSalary)));
      95  *
      96  * // Partition students into passing and failing
      97  * Map<Boolean, List<Student>> passingFailing = 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      * Construct an {@code IllegalStateException} with appropriate message.
     124      *
     125      * @param k the duplicate key
     126      * @param u 1st value to be accumulated/merged
     127      * @param v 2nd value to be accumulated/merged
     128      */
     129     private static IllegalStateException duplicateKeyException(
     130             Object k, Object u, Object v) {
     131         return new IllegalStateException(String.format(
     132             "Duplicate key %s (attempted merging values %s and %s)",
     133             k, u, v));
     134     }
     135
     136     /**
     137      * {@code BinaryOperator<Map>} that merges the contents of its right
     138      * argument into its left argument, throwing {@code IllegalStateException}
     139      * if duplicate keys are encountered.
     140      *
     141      * @param <K> type of the map keys
     142      * @param <V> type of the map values
     143      * @param <M> type of the map
     144      * @return a merge function for two maps
     145      */
     146     private static <K, V, M extends Map<K,V>>
     147     BinaryOperator<M> uniqKeysMapMerger() {
     148         return (m1, m2) -> {
     149             for (Map.Entry<K,V> e : m2.entrySet()) {
     150                 K k = e.getKey();
     151                 V v = Objects.requireNonNull(e.getValue());
     152                 V u = m1.putIfAbsent(k, v);
     153                 if (u != null) throw duplicateKeyException(k, u, v);
     154             }
     155             return m1;
     156         };
     157     }
     158
     159     /**
     160      * {@code BiConsumer<Map, T>} that accumulates (key, value) pairs
     161      * extracted from elements into the map, throwing {@code IllegalStateException}
     162      * if duplicate keys are encountered.
     163      *
     164      * @param keyMapper a function that maps an element into a key
     165      * @param valueMapper a function that maps an element into a value
     166      * @param <T> type of elements
     167      * @param <K> type of map keys
     168      * @param <V> type of map values
     169      * @return an accumulating consumer
     170      */
     171     private static <T, K, V>
     172     BiConsumer<Map<K, V>, T> uniqKeysMapAccumulator(Function<? super T, ? extends K> keyMapper,
     173                                                     Function<? super T, ? extends V> valueMapper) {
     174         return (map, element) -> {
     175             K k = keyMapper.apply(element);
     176             V v = Objects.requireNonNull(valueMapper.apply(element));
     177             V u = map.putIfAbsent(k, v);
     178             if (u != null) throw duplicateKeyException(k, u, v);
     179         };
     180     }
     181
     182     @SuppressWarnings("unchecked")
     183     private static <I, R> Function<I, R> castingIdentity() {
     184         return i -> (R) i;
     185     }
     186
     187     /**
     188      * Simple implementation class for {@code Collector}.
     189      *
     190      * @param <T> the type of elements to be collected
     191      * @param <R> the type of the result
     192      */
     193     static class CollectorImpl<T, A, R> implements Collector<T, A, R> {
     194         private final Supplier<A> supplier;
     195         private final BiConsumer<A, T> accumulator;
     196         private final BinaryOperator<A> combiner;
     197         private final Function<A, R> finisher;
     198         private final Set<Characteristics> characteristics;
     199
     200         CollectorImpl(Supplier<A> supplier,
     201                       BiConsumer<A, T> accumulator,
     202                       BinaryOperator<A> combiner,
     203                       Function<A,R> finisher,
     204                       Set<Characteristics> characteristics) {
     205             this.supplier = supplier;
     206             this.accumulator = accumulator;
     207             this.combiner = combiner;
     208             this.finisher = finisher;
     209             this.characteristics = characteristics;
     210         }
     211
     212         CollectorImpl(Supplier<A> supplier,
     213                       BiConsumer<A, T> accumulator,
     214                       BinaryOperator<A> combiner,
     215                       Set<Characteristics> characteristics) {
     216             this(supplier, accumulator, combiner, castingIdentity(), characteristics);
     217         }
     218
     219         @Override
     220         public BiConsumer<A, T> accumulator() {
     221             return accumulator;
     222         }
     223
     224         @Override
     225         public Supplier<A> supplier() {
     226             return supplier;
     227         }
     228
     229         @Override
     230         public BinaryOperator<A> combiner() {
     231             return combiner;
     232         }
     233
     234         @Override
     235         public Function<A, R> finisher() {
     236             return finisher;
     237         }
     238
     239         @Override
     240         public Set<Characteristics> characteristics() {
     241             return characteristics;
     242         }
     243     }
     244
     245     /**
     246      * Returns a {@code Collector} that accumulates the input elements into a
     247      * new {@code Collection}, in encounter order.  The {@code Collection} is
     248      * created by the provided factory.
     249      *
     250      * @param <T> the type of the input elements
     251      * @param <C> the type of the resulting {@code Collection}
     252      * @param collectionFactory a supplier providing a new empty {@code Collection}
     253      *                          into which the results will be inserted
     254      * @return a {@code Collector} which collects all the input elements into a
     255      * {@code Collection}, in encounter order
     256      */
     257     public static <T, C extends Collection<T>>
     258     Collector<T, ?, C> toCollection(Supplier<C> collectionFactory) {
     259         return new CollectorImpl<>(collectionFactory, Collection<T>::add,
     260                                    (r1, r2) -> { r1.addAll(r2); return r1; },
     261                                    CH_ID);
     262     }
     263
     264     /**
     265      * Returns a {@code Collector} that accumulates the input elements into a
     266      * new {@code List}. There are no guarantees on the type, mutability,
     267      * serializability, or thread-safety of the {@code List} returned; if more
     268      * control over the returned {@code List} is required, use {@link #toCollection(Supplier)}.
     269      *
     270      * @param <T> the type of the input elements
     271      * @return a {@code Collector} which collects all the input elements into a
     272      * {@code List}, in encounter order
     273      */
     274     public static <T>
     275     Collector<T, ?, List<T>> toList() {
     276         return new CollectorImpl<>((Supplier<List<T>>) ArrayList::new, List::add,
     277                                    (left, right) -> { left.addAll(right); return left; },
     278                                    CH_ID);
     279     }
     280
     281     /**
     282      * Returns a {@code Collector} that accumulates the input elements into a
     283      * new {@code Set}. There are no guarantees on the type, mutability,
     284      * serializability, or thread-safety of the {@code Set} returned; if more
     285      * control over the returned {@code Set} is required, use
     286      * {@link #toCollection(Supplier)}.
     287      *
     288      * <p>This is an {@link Collector.Characteristics#UNORDERED unordered}
     289      * Collector.
     290      *
     291      * @param <T> the type of the input elements
     292      * @return a {@code Collector} which collects all the input elements into a
     293      * {@code Set}
     294      */
     295     public static <T>
     296     Collector<T, ?, Set<T>> toSet() {
     297         return new CollectorImpl<>((Supplier<Set<T>>) HashSet::new, Set::add,
     298                                    (left, right) -> {
     299                                        if (left.size() < right.size()) {
     300                                            right.addAll(left); return right;
     301                                        } else {
     302                                            left.addAll(right); return left;
     303                                        }
     304                                    },
     305                                    CH_UNORDERED_ID);
     306     }
     307
     308     /**
     309      * Returns a {@code Collector} that concatenates the input elements into a
     310      * {@code String}, in encounter order.
     311      *
     312      * @return a {@code Collector} that concatenates the input elements into a
     313      * {@code String}, in encounter order
     314      */
     315     public static Collector<CharSequence, ?, String> joining() {
     316         return new CollectorImpl<CharSequence, StringBuilder, String>(
     317                 StringBuilder::new, StringBuilder::append,
     318                 (r1, r2) -> { r1.append(r2); return r1; },
     319                 StringBuilder::toString, CH_NOID);
     320     }
     321
     322     /**
     323      * Returns a {@code Collector} that concatenates the input elements,
     324      * separated by the specified delimiter, in encounter order.
     325      *
     326      * @param delimiter the delimiter to be used between each element
     327      * @return A {@code Collector} which concatenates CharSequence elements,
     328      * separated by the specified delimiter, in encounter order
     329      */
     330     public static Collector<CharSequence, ?, String> joining(CharSequence delimiter) {
     331         return joining(delimiter, "", "");
     332     }
     333
     334     /**
     335      * Returns a {@code Collector} that concatenates the input elements,
     336      * separated by the specified delimiter, with the specified prefix and
     337      * suffix, in encounter order.
     338      *
     339      * @param delimiter the delimiter to be used between each element
     340      * @param  prefix the sequence of characters to be used at the beginning
     341      *                of the joined result
     342      * @param  suffix the sequence of characters to be used at the end
     343      *                of the joined result
     344      * @return A {@code Collector} which concatenates CharSequence elements,
     345      * separated by the specified delimiter, in encounter order
     346      */
     347     public static Collector<CharSequence, ?, String> joining(CharSequence delimiter,
     348                                                              CharSequence prefix,
     349                                                              CharSequence suffix) {
     350         return new CollectorImpl<>(
     351                 () -> new StringJoiner(delimiter, prefix, suffix),
     352                 StringJoiner::add, StringJoiner::merge,
     353                 StringJoiner::toString, CH_NOID);
     354     }
     355
     356     /**
     357      * {@code BinaryOperator<Map>} that merges the contents of its right
     358      * argument into its left argument, using the provided merge function to
     359      * handle duplicate keys.
     360      *
     361      * @param <K> type of the map keys
     362      * @param <V> type of the map values
     363      * @param <M> type of the map
     364      * @param mergeFunction A merge function suitable for
     365      * {@link Map#merge(Object, Object, BiFunction) Map.merge()}
     366      * @return a merge function for two maps
     367      */
     368     private static <K, V, M extends Map<K,V>>
     369     BinaryOperator<M> mapMerger(BinaryOperator<V> mergeFunction) {
     370         return (m1, m2) -> {
     371             for (Map.Entry<K,V> e : m2.entrySet())
     372                 m1.merge(e.getKey(), e.getValue(), mergeFunction);
     373             return m1;
     374         };
     375     }
     376
     377     /**
     378      * Adapts a {@code Collector} accepting elements of type {@code U} to one
     379      * accepting elements of type {@code T} by applying a mapping function to
     380      * each input element before accumulation.
     381      *
     382      * @apiNote
     383      * The {@code mapping()} collectors are most useful when used in a
     384      * multi-level reduction, such as downstream of a {@code groupingBy} or
     385      * {@code partitioningBy}.  For example, given a stream of
     386      * {@code Person}, to accumulate the set of last names in each city:
     387      * <pre>{@code
     388      * Map<City, Set<String>> lastNamesByCity
     389      *   = people.stream().collect(
     390      *     groupingBy(Person::getCity,
     391      *                mapping(Person::getLastName,
     392      *                        toSet())));
     393      * }</pre>
     394      *
     395      * @param <T> the type of the input elements
     396      * @param <U> type of elements accepted by downstream collector
     397      * @param <A> intermediate accumulation type of the downstream collector
     398      * @param <R> result type of collector
     399      * @param mapper a function to be applied to the input elements
     400      * @param downstream a collector which will accept mapped values
     401      * @return a collector which applies the mapping function to the input
     402      * elements and provides the mapped results to the downstream collector
     403      */
     404     public static <T, U, A, R>
     405     Collector<T, ?, R> mapping(Function<? super T, ? extends U> mapper,
     406                                Collector<? super U, A, R> downstream) {
     407         BiConsumer<A, ? super U> downstreamAccumulator = downstream.accumulator();
     408         return new CollectorImpl<>(downstream.supplier(),
     409                                    (r, t) -> downstreamAccumulator.accept(r, mapper.apply(t)),
     410                                    downstream.combiner(), downstream.finisher(),
     411                                    downstream.characteristics());
     412     }
     413
     414     /**
     415      * Adapts a {@code Collector} accepting elements of type {@code U} to one
     416      * accepting elements of type {@code T} by applying a flat mapping function
     417      * to each input element before accumulation.  The flat mapping function
     418      * maps an input element to a {@link Stream stream} covering zero or more
     419      * output elements that are then accumulated downstream.  Each mapped stream
     420      * is {@link java.util.stream.BaseStream#close() closed} after its contents
     421      * have been placed downstream.  (If a mapped stream is {@code null}
     422      * an empty stream is used, instead.)
     423      *
     424      * @apiNote
     425      * The {@code flatMapping()} collectors are most useful when used in a
     426      * multi-level reduction, such as downstream of a {@code groupingBy} or
     427      * {@code partitioningBy}.  For example, given a stream of
     428      * {@code Order}, to accumulate the set of line items for each customer:
     429      * <pre>{@code
     430      * Map<String, Set<LineItem>> itemsByCustomerName
     431      *   = orders.stream().collect(
     432      *     groupingBy(Order::getCustomerName,
     433      *                flatMapping(order -> order.getLineItems().stream(),
     434      *                            toSet())));
     435      * }</pre>
     436      *
     437      * @param <T> the type of the input elements
     438      * @param <U> type of elements accepted by downstream collector
     439      * @param <A> intermediate accumulation type of the downstream collector
     440      * @param <R> result type of collector
     441      * @param mapper a function to be applied to the input elements, which
     442      * returns a stream of results
     443      * @param downstream a collector which will receive the elements of the
     444      * stream returned by mapper
     445      * @return a collector which applies the mapping function to the input
     446      * elements and provides the flat mapped results to the downstream collector
     447      * @since 9
     448      */
     449     public static <T, U, A, R>
     450     Collector<T, ?, R> flatMapping(Function<? super T, ? extends Stream<? extends U>> mapper,
     451                                    Collector<? super U, A, R> downstream) {
     452         BiConsumer<A, ? super U> downstreamAccumulator = downstream.accumulator();
     453         return new CollectorImpl<>(downstream.supplier(),
     454                             (r, t) -> {
     455                                 try (Stream<? extends U> result = mapper.apply(t)) {
     456                                     if (result != null)
     457                                         result.sequential().forEach(u -> downstreamAccumulator.accept(r, u));
     458                                 }
     459                             },
     460                             downstream.combiner(), downstream.finisher(),
     461                             downstream.characteristics());
     462     }
     463
     464     /**
     465      * Adapts a {@code Collector} to one accepting elements of the same type
     466      * {@code T} by applying the predicate to each input element and only
     467      * accumulating if the predicate returns {@code true}.
     468      *
     469      * @apiNote
     470      * The {@code filtering()} collectors are most useful when used in a
     471      * multi-level reduction, such as downstream of a {@code groupingBy} or
     472      * {@code partitioningBy}.  For example, given a stream of
     473      * {@code Employee}, to accumulate the employees in each department that have a
     474      * salary above a certain threshold:
     475      * <pre>{@code
     476      * Map<Department, Set<Employee>> wellPaidEmployeesByDepartment
     477      *   = employees.stream().collect(
     478      *     groupingBy(Employee::getDepartment,
     479      *                filtering(e -> e.getSalary() > 2000,
     480      *                          toSet())));
     481      * }</pre>
     482      * A filtering collector differs from a stream's {@code filter()} operation.
     483      * In this example, suppose there are no employees whose salary is above the
     484      * threshold in some department.  Using a filtering collector as shown above
     485      * would result in a mapping from that department to an empty {@code Set}.
     486      * If a stream {@code filter()} operation were done instead, there would be
     487      * no mapping for that department at all.
     488      *
     489      * @param <T> the type of the input elements
     490      * @param <A> intermediate accumulation type of the downstream collector
     491      * @param <R> result type of collector
     492      * @param predicate a predicate to be applied to the input elements
     493      * @param downstream a collector which will accept values that match the
     494      * predicate
     495      * @return a collector which applies the predicate to the input elements
     496      * and provides matching elements to the downstream collector
     497      * @since 9
     498      */
     499     public static <T, A, R>
     500     Collector<T, ?, R> filtering(Predicate<? super T> predicate,
     501                                  Collector<? super T, A, R> downstream) {
     502         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
     503         return new CollectorImpl<>(downstream.supplier(),
     504                                    (r, t) -> {
     505                                        if (predicate.test(t)) {
     506                                            downstreamAccumulator.accept(r, t);
     507                                        }
     508                                    },
     509                                    downstream.combiner(), downstream.finisher(),
     510                                    downstream.characteristics());
     511     }
     512
     513     /**
     514      * Adapts a {@code Collector} to perform an additional finishing
     515      * transformation.  For example, one could adapt the {@link #toList()}
     516      * collector to always produce an immutable list with:
     517      * <pre>{@code
     518      * List<String> list = people.stream().collect(
     519      *   collectingAndThen(toList(),
     520      *                     Collections::unmodifiableList));
     521      * }</pre>
     522      *
     523      * @param <T> the type of the input elements
     524      * @param <A> intermediate accumulation type of the downstream collector
     525      * @param <R> result type of the downstream collector
     526      * @param <RR> result type of the resulting collector
     527      * @param downstream a collector
     528      * @param finisher a function to be applied to the final result of the downstream collector
     529      * @return a collector which performs the action of the downstream collector,
     530      * followed by an additional finishing step
     531      */
     532     public static<T,A,R,RR> Collector<T,A,RR> collectingAndThen(Collector<T,A,R> downstream,
     533                                                                 Function<R,RR> finisher) {
     534         Set<Collector.Characteristics> characteristics = downstream.characteristics();
     535         if (characteristics.contains(Collector.Characteristics.IDENTITY_FINISH)) {
     536             if (characteristics.size() == 1)
     537                 characteristics = Collectors.CH_NOID;
     538             else {
     539                 characteristics = EnumSet.copyOf(characteristics);
     540                 characteristics.remove(Collector.Characteristics.IDENTITY_FINISH);
     541                 characteristics = Collections.unmodifiableSet(characteristics);
     542             }
     543         }
     544         return new CollectorImpl<>(downstream.supplier(),
     545                                    downstream.accumulator(),
     546                                    downstream.combiner(),
     547                                    downstream.finisher().andThen(finisher),
     548                                    characteristics);
     549     }
     550
     551     /**
     552      * Returns a {@code Collector} accepting elements of type {@code T} that
     553      * counts the number of input elements.  If no elements are present, the
     554      * result is 0.
     555      *
     556      * @implSpec
     557      * This produces a result equivalent to:
     558      * <pre>{@code
     559      *     reducing(0L, e -> 1L, Long::sum)
     560      * }</pre>
     561      *
     562      * @param <T> the type of the input elements
     563      * @return a {@code Collector} that counts the input elements
     564      */
     565     public static <T> Collector<T, ?, Long>
     566     counting() {
     567         return summingLong(e -> 1L);
     568     }
     569
     570     /**
     571      * Returns a {@code Collector} that produces the minimal element according
     572      * to a given {@code Comparator}, described as an {@code Optional<T>}.
     573      *
     574      * @implSpec
     575      * This produces a result equivalent to:
     576      * <pre>{@code
     577      *     reducing(BinaryOperator.minBy(comparator))
     578      * }</pre>
     579      *
     580      * @param <T> the type of the input elements
     581      * @param comparator a {@code Comparator} for comparing elements
     582      * @return a {@code Collector} that produces the minimal value
     583      */
     584     public static <T> Collector<T, ?, Optional<T>>
     585     minBy(Comparator<? super T> comparator) {
     586         return reducing(BinaryOperator.minBy(comparator));
     587     }
     588
     589     /**
     590      * Returns a {@code Collector} that produces the maximal element according
     591      * to a given {@code Comparator}, described as an {@code Optional<T>}.
     592      *
     593      * @implSpec
     594      * This produces a result equivalent to:
     595      * <pre>{@code
     596      *     reducing(BinaryOperator.maxBy(comparator))
     597      * }</pre>
     598      *
     599      * @param <T> the type of the input elements
     600      * @param comparator a {@code Comparator} for comparing elements
     601      * @return a {@code Collector} that produces the maximal value
     602      */
     603     public static <T> Collector<T, ?, Optional<T>>
     604     maxBy(Comparator<? super T> comparator) {
     605         return reducing(BinaryOperator.maxBy(comparator));
     606     }
     607
     608     /**
     609      * Returns a {@code Collector} that produces the sum of a integer-valued
     610      * function applied to the input elements.  If no elements are present,
     611      * the result is 0.
     612      *
     613      * @param <T> the type of the input elements
     614      * @param mapper a function extracting the property to be summed
     615      * @return a {@code Collector} that produces the sum of a derived property
     616      */
     617     public static <T> Collector<T, ?, Integer>
     618     summingInt(ToIntFunction<? super T> mapper) {
     619         return new CollectorImpl<>(
     620                 () -> new int[1],
     621                 (a, t) -> { a[0] += mapper.applyAsInt(t); },
     622                 (a, b) -> { a[0] += b[0]; return a; },
     623                 a -> a[0], CH_NOID);
     624     }
     625
     626     /**
     627      * Returns a {@code Collector} that produces the sum of a long-valued
     628      * function applied to the input elements.  If no elements are present,
     629      * the result is 0.
     630      *
     631      * @param <T> the type of the input elements
     632      * @param mapper a function extracting the property to be summed
     633      * @return a {@code Collector} that produces the sum of a derived property
     634      */
     635     public static <T> Collector<T, ?, Long>
     636     summingLong(ToLongFunction<? super T> mapper) {
     637         return new CollectorImpl<>(
     638                 () -> new long[1],
     639                 (a, t) -> { a[0] += mapper.applyAsLong(t); },
     640                 (a, b) -> { a[0] += b[0]; return a; },
     641                 a -> a[0], CH_NOID);
     642     }
     643
     644     /**
     645      * Returns a {@code Collector} that produces the sum of a double-valued
     646      * function applied to the input elements.  If no elements are present,
     647      * the result is 0.
     648      *
     649      * <p>The sum returned can vary depending upon the order in which
     650      * values are recorded, due to accumulated rounding error in
     651      * addition of values of differing magnitudes. Values sorted by increasing
     652      * absolute magnitude tend to yield more accurate results.  If any recorded
     653      * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
     654      * sum will be {@code NaN}.
     655      *
     656      * @param <T> the type of the input elements
     657      * @param mapper a function extracting the property to be summed
     658      * @return a {@code Collector} that produces the sum of a derived property
     659      */
     660     public static <T> Collector<T, ?, Double>
     661     summingDouble(ToDoubleFunction<? super T> mapper) {
     662         /*
     663          * In the arrays allocated for the collect operation, index 0
     664          * holds the high-order bits of the running sum, index 1 holds
     665          * the low-order bits of the sum computed via compensated
     666          * summation, and index 2 holds the simple sum used to compute
     667          * the proper result if the stream contains infinite values of
     668          * the same sign.
     669          */
     670         return new CollectorImpl<>(
     671                 () -> new double[3],
     672                 (a, t) -> { double val = mapper.applyAsDouble(t);
     673                             sumWithCompensation(a, val);
     674                             a[2] += val;},
     675                 (a, b) -> { sumWithCompensation(a, b[0]);
     676                             a[2] += b[2];
     677                             return sumWithCompensation(a, b[1]); },
     678                 a -> computeFinalSum(a),
     679                 CH_NOID);
     680     }
     681
     682     /**
     683      * Incorporate a new double value using Kahan summation /
     684      * compensation summation.
     685      *
     686      * High-order bits of the sum are in intermediateSum[0], low-order
     687      * bits of the sum are in intermediateSum[1], any additional
     688      * elements are application-specific.
     689      *
     690      * @param intermediateSum the high-order and low-order words of the intermediate sum
     691      * @param value the name value to be included in the running sum
     692      */
     693     static double[] sumWithCompensation(double[] intermediateSum, double value) {
     694         double tmp = value - intermediateSum[1];
     695         double sum = intermediateSum[0];
     696         double velvel = sum + tmp; // Little wolf of rounding error
     697         intermediateSum[1] = (velvel - sum) - tmp;
     698         intermediateSum[0] = velvel;
     699         return intermediateSum;
     700     }
     701
     702     /**
     703      * If the compensated sum is spuriously NaN from accumulating one
     704      * or more same-signed infinite values, return the
     705      * correctly-signed infinity stored in the simple sum.
     706      */
     707     static double computeFinalSum(double[] summands) {
     708         // Better error bounds to add both terms as the final sum
     709         double tmp = summands[0] + summands[1];
     710         double simpleSum = summands[summands.length - 1];
     711         if (Double.isNaN(tmp) && Double.isInfinite(simpleSum))
     712             return simpleSum;
     713         else
     714             return tmp;
     715     }
     716
     717     /**
     718      * Returns a {@code Collector} that produces the arithmetic mean of an integer-valued
     719      * function applied to the input elements.  If no elements are present,
     720      * the result is 0.
     721      *
     722      * @param <T> the type of the input elements
     723      * @param mapper a function extracting the property to be averaged
     724      * @return a {@code Collector} that produces the arithmetic mean of a
     725      * derived property
     726      */
     727     public static <T> Collector<T, ?, Double>
     728     averagingInt(ToIntFunction<? super T> mapper) {
     729         return new CollectorImpl<>(
     730                 () -> new long[2],
     731                 (a, t) -> { a[0] += mapper.applyAsInt(t); a[1]++; },
     732                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
     733                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
     734     }
     735
     736     /**
     737      * Returns a {@code Collector} that produces the arithmetic mean of a long-valued
     738      * function applied to the input elements.  If no elements are present,
     739      * the result is 0.
     740      *
     741      * @param <T> the type of the input elements
     742      * @param mapper a function extracting the property to be averaged
     743      * @return a {@code Collector} that produces the arithmetic mean of a
     744      * derived property
     745      */
     746     public static <T> Collector<T, ?, Double>
     747     averagingLong(ToLongFunction<? super T> mapper) {
     748         return new CollectorImpl<>(
     749                 () -> new long[2],
     750                 (a, t) -> { a[0] += mapper.applyAsLong(t); a[1]++; },
     751                 (a, b) -> { a[0] += b[0]; a[1] += b[1]; return a; },
     752                 a -> (a[1] == 0) ? 0.0d : (double) a[0] / a[1], CH_NOID);
     753     }
     754
     755     /**
     756      * Returns a {@code Collector} that produces the arithmetic mean of a double-valued
     757      * function applied to the input elements.  If no elements are present,
     758      * the result is 0.
     759      *
     760      * <p>The average returned can vary depending upon the order in which
     761      * values are recorded, due to accumulated rounding error in
     762      * addition of values of differing magnitudes. Values sorted by increasing
     763      * absolute magnitude tend to yield more accurate results.  If any recorded
     764      * value is a {@code NaN} or the sum is at any point a {@code NaN} then the
     765      * average will be {@code NaN}.
     766      *
     767      * @implNote The {@code double} format can represent all
     768      * consecutive integers in the range -2<sup>53</sup> to
     769      * 2<sup>53</sup>. If the pipeline has more than 2<sup>53</sup>
     770      * values, the divisor in the average computation will saturate at
     771      * 2<sup>53</sup>, leading to additional numerical errors.
     772      *
     773      * @param <T> the type of the input elements
     774      * @param mapper a function extracting the property to be averaged
     775      * @return a {@code Collector} that produces the arithmetic mean of a
     776      * derived property
     777      */
     778     public static <T> Collector<T, ?, Double>
     779     averagingDouble(ToDoubleFunction<? super T> mapper) {
     780         /*
     781          * In the arrays allocated for the collect operation, index 0
     782          * holds the high-order bits of the running sum, index 1 holds
     783          * the low-order bits of the sum computed via compensated
     784          * summation, and index 2 holds the number of values seen.
     785          */
     786         return new CollectorImpl<>(
     787                 () -> new double[4],
     788                 (a, t) -> { double val = mapper.applyAsDouble(t); sumWithCompensation(a, val); a[2]++; a[3]+= val;},
     789                 (a, b) -> { sumWithCompensation(a, b[0]); sumWithCompensation(a, b[1]); a[2] += b[2]; a[3] += b[3]; return a; },
     790                 a -> (a[2] == 0) ? 0.0d : (computeFinalSum(a) / a[2]),
     791                 CH_NOID);
     792     }
     793
     794     /**
     795      * Returns a {@code Collector} which performs a reduction of its
     796      * input elements under a specified {@code BinaryOperator} using the
     797      * provided identity.
     798      *
     799      * @apiNote
     800      * The {@code reducing()} collectors are most useful when used in a
     801      * multi-level reduction, downstream of {@code groupingBy} or
     802      * {@code partitioningBy}.  To perform a simple reduction on a stream,
     803      * use {@link Stream#reduce(Object, BinaryOperator)}} instead.
     804      *
     805      * @param <T> element type for the input and output of the reduction
     806      * @param identity the identity value for the reduction (also, the value
     807      *                 that is returned when there are no input elements)
     808      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
     809      * @return a {@code Collector} which implements the reduction operation
     810      *
     811      * @see #reducing(BinaryOperator)
     812      * @see #reducing(Object, Function, BinaryOperator)
     813      */
     814     public static <T> Collector<T, ?, T>
     815     reducing(T identity, BinaryOperator<T> op) {
     816         return new CollectorImpl<>(
     817                 boxSupplier(identity),
     818                 (a, t) -> { a[0] = op.apply(a[0], t); },
     819                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
     820                 a -> a[0],
     821                 CH_NOID);
     822     }
     823
     824     @SuppressWarnings("unchecked")
     825     private static <T> Supplier<T[]> boxSupplier(T identity) {
     826         return () -> (T[]) new Object[] { identity };
     827     }
     828
     829     /**
     830      * Returns a {@code Collector} which performs a reduction of its
     831      * input elements under a specified {@code BinaryOperator}.  The result
     832      * is described as an {@code Optional<T>}.
     833      *
     834      * @apiNote
     835      * The {@code reducing()} collectors are most useful when used in a
     836      * multi-level reduction, downstream of {@code groupingBy} or
     837      * {@code partitioningBy}.  To perform a simple reduction on a stream,
     838      * use {@link Stream#reduce(BinaryOperator)} instead.
     839      *
     840      * <p>For example, given a stream of {@code Person}, to calculate tallest
     841      * person in each city:
     842      * <pre>{@code
     843      * Comparator<Person> byHeight = Comparator.comparing(Person::getHeight);
     844      * Map<City, Optional<Person>> tallestByCity
     845      *   = people.stream().collect(
     846      *     groupingBy(Person::getCity,
     847      *                reducing(BinaryOperator.maxBy(byHeight))));
     848      * }</pre>
     849      *
     850      * @param <T> element type for the input and output of the reduction
     851      * @param op a {@code BinaryOperator<T>} used to reduce the input elements
     852      * @return a {@code Collector} which implements the reduction operation
     853      *
     854      * @see #reducing(Object, BinaryOperator)
     855      * @see #reducing(Object, Function, BinaryOperator)
     856      */
     857     public static <T> Collector<T, ?, Optional<T>>
     858     reducing(BinaryOperator<T> op) {
     859         class OptionalBox implements Consumer<T> {
     860             T value = null;
     861             boolean present = false;
     862
     863             @Override
     864             public void accept(T t) {
     865                 if (present) {
     866                     value = op.apply(value, t);
     867                 }
     868                 else {
     869                     value = t;
     870                     present = true;
     871                 }
     872             }
     873         }
     874
     875         return new CollectorImpl<T, OptionalBox, Optional<T>>(
     876                 OptionalBox::new, OptionalBox::accept,
     877                 (a, b) -> { if (b.present) a.accept(b.value); return a; },
     878                 a -> Optional.ofNullable(a.value), CH_NOID);
     879     }
     880
     881     /**
     882      * Returns a {@code Collector} which performs a reduction of its
     883      * input elements under a specified mapping function and
     884      * {@code BinaryOperator}. This is a generalization of
     885      * {@link #reducing(Object, BinaryOperator)} which allows a transformation
     886      * of the elements before reduction.
     887      *
     888      * @apiNote
     889      * The {@code reducing()} collectors are most useful when used in a
     890      * multi-level reduction, downstream of {@code groupingBy} or
     891      * {@code partitioningBy}.  To perform a simple map-reduce on a stream,
     892      * use {@link Stream#map(Function)} and {@link Stream#reduce(Object, BinaryOperator)}
     893      * instead.
     894      *
     895      * <p>For example, given a stream of {@code Person}, to calculate the longest
     896      * last name of residents in each city:
     897      * <pre>{@code
     898      * Comparator<String> byLength = Comparator.comparing(String::length);
     899      * Map<City, String> longestLastNameByCity
     900      *   = people.stream().collect(
     901      *     groupingBy(Person::getCity,
     902      *                reducing("",
     903      *                         Person::getLastName,
     904      *                         BinaryOperator.maxBy(byLength))));
     905      * }</pre>
     906      *
     907      * @param <T> the type of the input elements
     908      * @param <U> the type of the mapped values
     909      * @param identity the identity value for the reduction (also, the value
     910      *                 that is returned when there are no input elements)
     911      * @param mapper a mapping function to apply to each input value
     912      * @param op a {@code BinaryOperator<U>} used to reduce the mapped values
     913      * @return a {@code Collector} implementing the map-reduce operation
     914      *
     915      * @see #reducing(Object, BinaryOperator)
     916      * @see #reducing(BinaryOperator)
     917      */
     918     public static <T, U>
     919     Collector<T, ?, U> reducing(U identity,
     920                                 Function<? super T, ? extends U> mapper,
     921                                 BinaryOperator<U> op) {
     922         return new CollectorImpl<>(
     923                 boxSupplier(identity),
     924                 (a, t) -> { a[0] = op.apply(a[0], mapper.apply(t)); },
     925                 (a, b) -> { a[0] = op.apply(a[0], b[0]); return a; },
     926                 a -> a[0], CH_NOID);
     927     }
     928
     929     /**
     930      * Returns a {@code Collector} implementing a "group by" operation on
     931      * input elements of type {@code T}, grouping elements according to a
     932      * classification function, and returning the results in a {@code Map}.
     933      *
     934      * <p>The classification function maps elements to some key type {@code K}.
     935      * The collector produces a {@code Map<K, List<T>>} whose keys are the
     936      * values resulting from applying the classification function to the input
     937      * elements, and whose corresponding values are {@code List}s containing the
     938      * input elements which map to the associated key under the classification
     939      * function.
     940      *
     941      * <p>There are no guarantees on the type, mutability, serializability, or
     942      * thread-safety of the {@code Map} or {@code List} objects returned.
     943      * @implSpec
     944      * This produces a result similar to:
     945      * <pre>{@code
     946      *     groupingBy(classifier, toList());
     947      * }</pre>
     948      *
     949      * @implNote
     950      * The returned {@code Collector} is not concurrent.  For parallel stream
     951      * pipelines, the {@code combiner} function operates by merging the keys
     952      * from one map into another, which can be an expensive operation.  If
     953      * preservation of the order in which elements appear in the resulting {@code Map}
     954      * collector is not required, using {@link #groupingByConcurrent(Function)}
     955      * may offer better parallel performance.
     956      *
     957      * @param <T> the type of the input elements
     958      * @param <K> the type of the keys
     959      * @param classifier the classifier function mapping input elements to keys
     960      * @return a {@code Collector} implementing the group-by operation
     961      *
     962      * @see #groupingBy(Function, Collector)
     963      * @see #groupingBy(Function, Supplier, Collector)
     964      * @see #groupingByConcurrent(Function)
     965      */
     966     public static <T, K> Collector<T, ?, Map<K, List<T>>>
     967     groupingBy(Function<? super T, ? extends K> classifier) {
     968         return groupingBy(classifier, toList());
     969     }
     970
     971     /**
     972      * Returns a {@code Collector} implementing a cascaded "group by" operation
     973      * on input elements of type {@code T}, grouping elements according to a
     974      * classification function, and then performing a reduction operation on
     975      * the values associated with a given key using the specified downstream
     976      * {@code Collector}.
     977      *
     978      * <p>The classification function maps elements to some key type {@code K}.
     979      * The downstream collector operates on elements of type {@code T} and
     980      * produces a result of type {@code D}. The resulting collector produces a
     981      * {@code Map<K, D>}.
     982      *
     983      * <p>There are no guarantees on the type, mutability,
     984      * serializability, or thread-safety of the {@code Map} returned.
     985      *
     986      * <p>For example, to compute the set of last names of people in each city:
     987      * <pre>{@code
     988      * Map<City, Set<String>> namesByCity
     989      *   = people.stream().collect(
     990      *     groupingBy(Person::getCity,
     991      *                mapping(Person::getLastName,
     992      *                        toSet())));
     993      * }</pre>
     994      *
     995      * @implNote
     996      * The returned {@code Collector} is not concurrent.  For parallel stream
     997      * pipelines, the {@code combiner} function operates by merging the keys
     998      * from one map into another, which can be an expensive operation.  If
     999      * preservation of the order in which elements are presented to the downstream
    1000      * collector is not required, using {@link #groupingByConcurrent(Function, Collector)}
    1001      * may offer better parallel performance.
    1002      *
    1003      * @param <T> the type of the input elements
    1004      * @param <K> the type of the keys
    1005      * @param <A> the intermediate accumulation type of the downstream collector
    1006      * @param <D> the result type of the downstream reduction
    1007      * @param classifier a classifier function mapping input elements to keys
    1008      * @param downstream a {@code Collector} implementing the downstream reduction
    1009      * @return a {@code Collector} implementing the cascaded group-by operation
    1010      * @see #groupingBy(Function)
    1011      *
    1012      * @see #groupingBy(Function, Supplier, Collector)
    1013      * @see #groupingByConcurrent(Function, Collector)
    1014      */
    1015     public static <T, K, A, D>
    1016     Collector<T, ?, Map<K, D>> groupingBy(Function<? super T, ? extends K> classifier,
    1017                                           Collector<? super T, A, D> downstream) {
    1018         return groupingBy(classifier, HashMap::new, downstream);
    1019     }
    1020
    1021     /**
    1022      * Returns a {@code Collector} implementing a cascaded "group by" operation
    1023      * on input elements of type {@code T}, grouping elements according to a
    1024      * classification function, and then performing a reduction operation on
    1025      * the values associated with a given key using the specified downstream
    1026      * {@code Collector}.  The {@code Map} produced by the Collector is created
    1027      * with the supplied factory function.
    1028      *
    1029      * <p>The classification function maps elements to some key type {@code K}.
    1030      * The downstream collector operates on elements of type {@code T} and
    1031      * produces a result of type {@code D}. The resulting collector produces a
    1032      * {@code Map<K, D>}.
    1033      *
    1034      * <p>For example, to compute the set of last names of people in each city,
    1035      * where the city names are sorted:
    1036      * <pre>{@code
    1037      * Map<City, Set<String>> namesByCity
    1038      *   = people.stream().collect(
    1039      *     groupingBy(Person::getCity,
    1040      *                TreeMap::new,
    1041      *                mapping(Person::getLastName,
    1042      *                        toSet())));
    1043      * }</pre>
    1044      *
    1045      * @implNote
    1046      * The returned {@code Collector} is not concurrent.  For parallel stream
    1047      * pipelines, the {@code combiner} function operates by merging the keys
    1048      * from one map into another, which can be an expensive operation.  If
    1049      * preservation of the order in which elements are presented to the downstream
    1050      * collector is not required, using {@link #groupingByConcurrent(Function, Supplier, Collector)}
    1051      * may offer better parallel performance.
    1052      *
    1053      * @param <T> the type of the input elements
    1054      * @param <K> the type of the keys
    1055      * @param <A> the intermediate accumulation type of the downstream collector
    1056      * @param <D> the result type of the downstream reduction
    1057      * @param <M> the type of the resulting {@code Map}
    1058      * @param classifier a classifier function mapping input elements to keys
    1059      * @param downstream a {@code Collector} implementing the downstream reduction
    1060      * @param mapFactory a supplier providing a new empty {@code Map}
    1061      *                   into which the results will be inserted
    1062      * @return a {@code Collector} implementing the cascaded group-by operation
    1063      *
    1064      * @see #groupingBy(Function, Collector)
    1065      * @see #groupingBy(Function)
    1066      * @see #groupingByConcurrent(Function, Supplier, Collector)
    1067      */
    1068     public static <T, K, D, A, M extends Map<K, D>>
    1069     Collector<T, ?, M> groupingBy(Function<? super T, ? extends K> classifier,
    1070                                   Supplier<M> mapFactory,
    1071                                   Collector<? super T, A, D> downstream) {
    1072         Supplier<A> downstreamSupplier = downstream.supplier();
    1073         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
    1074         BiConsumer<Map<K, A>, T> accumulator = (m, t) -> {
    1075             K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
    1076             A container = m.computeIfAbsent(key, k -> downstreamSupplier.get());
    1077             downstreamAccumulator.accept(container, t);
    1078         };
    1079         BinaryOperator<Map<K, A>> merger = Collectors.<K, A, Map<K, A>>mapMerger(downstream.combiner());
    1080         @SuppressWarnings("unchecked")
    1081         Supplier<Map<K, A>> mangledFactory = (Supplier<Map<K, A>>) mapFactory;
    1082
    1083         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
    1084             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_ID);
    1085         }
    1086         else {
    1087             @SuppressWarnings("unchecked")
    1088             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
    1089             Function<Map<K, A>, M> finisher = intermediate -> {
    1090                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
    1091                 @SuppressWarnings("unchecked")
    1092                 M castResult = (M) intermediate;
    1093                 return castResult;
    1094             };
    1095             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_NOID);
    1096         }
    1097     }
    1098
    1099     /**
    1100      * Returns a concurrent {@code Collector} implementing a "group by"
    1101      * operation on input elements of type {@code T}, grouping elements
    1102      * according to a classification function.
    1103      *
    1104      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1105      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1106      *
    1107      * <p>The classification function maps elements to some key type {@code K}.
    1108      * The collector produces a {@code ConcurrentMap<K, List<T>>} whose keys are the
    1109      * values resulting from applying the classification function to the input
    1110      * elements, and whose corresponding values are {@code List}s containing the
    1111      * input elements which map to the associated key under the classification
    1112      * function.
    1113      *
    1114      * <p>There are no guarantees on the type, mutability, or serializability
    1115      * of the {@code ConcurrentMap} or {@code List} objects returned, or of the
    1116      * thread-safety of the {@code List} objects returned.
    1117      * @implSpec
    1118      * This produces a result similar to:
    1119      * <pre>{@code
    1120      *     groupingByConcurrent(classifier, toList());
    1121      * }</pre>
    1122      *
    1123      * @param <T> the type of the input elements
    1124      * @param <K> the type of the keys
    1125      * @param classifier a classifier function mapping input elements to keys
    1126      * @return a concurrent, unordered {@code Collector} implementing the group-by operation
    1127      *
    1128      * @see #groupingBy(Function)
    1129      * @see #groupingByConcurrent(Function, Collector)
    1130      * @see #groupingByConcurrent(Function, Supplier, Collector)
    1131      */
    1132     public static <T, K>
    1133     Collector<T, ?, ConcurrentMap<K, List<T>>>
    1134     groupingByConcurrent(Function<? super T, ? extends K> classifier) {
    1135         return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList());
    1136     }
    1137
    1138     /**
    1139      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
    1140      * operation on input elements of type {@code T}, grouping elements
    1141      * according to a classification function, and then performing a reduction
    1142      * operation on the values associated with a given key using the specified
    1143      * downstream {@code Collector}.
    1144      *
    1145      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1146      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1147      *
    1148      * <p>The classification function maps elements to some key type {@code K}.
    1149      * The downstream collector operates on elements of type {@code T} and
    1150      * produces a result of type {@code D}. The resulting collector produces a
    1151      * {@code ConcurrentMap<K, D>}.
    1152      *
    1153      * <p>There are no guarantees on the type, mutability, or serializability
    1154      * of the {@code ConcurrentMap} returned.
    1155      *
    1156      * <p>For example, to compute the set of last names of people in each city,
    1157      * where the city names are sorted:
    1158      * <pre>{@code
    1159      * ConcurrentMap<City, Set<String>> namesByCity
    1160      *   = people.stream().collect(
    1161      *     groupingByConcurrent(Person::getCity,
    1162      *                          mapping(Person::getLastName,
    1163      *                                  toSet())));
    1164      * }</pre>
    1165      *
    1166      * @param <T> the type of the input elements
    1167      * @param <K> the type of the keys
    1168      * @param <A> the intermediate accumulation type of the downstream collector
    1169      * @param <D> the result type of the downstream reduction
    1170      * @param classifier a classifier function mapping input elements to keys
    1171      * @param downstream a {@code Collector} implementing the downstream reduction
    1172      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
    1173      *
    1174      * @see #groupingBy(Function, Collector)
    1175      * @see #groupingByConcurrent(Function)
    1176      * @see #groupingByConcurrent(Function, Supplier, Collector)
    1177      */
    1178     public static <T, K, A, D>
    1179     Collector<T, ?, ConcurrentMap<K, D>> groupingByConcurrent(Function<? super T, ? extends K> classifier,
    1180                                                               Collector<? super T, A, D> downstream) {
    1181         return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream);
    1182     }
    1183
    1184     /**
    1185      * Returns a concurrent {@code Collector} implementing a cascaded "group by"
    1186      * operation on input elements of type {@code T}, grouping elements
    1187      * according to a classification function, and then performing a reduction
    1188      * operation on the values associated with a given key using the specified
    1189      * downstream {@code Collector}.  The {@code ConcurrentMap} produced by the
    1190      * Collector is created with the supplied factory function.
    1191      *
    1192      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1193      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1194      *
    1195      * <p>The classification function maps elements to some key type {@code K}.
    1196      * The downstream collector operates on elements of type {@code T} and
    1197      * produces a result of type {@code D}. The resulting collector produces a
    1198      * {@code ConcurrentMap<K, D>}.
    1199      *
    1200      * <p>For example, to compute the set of last names of people in each city,
    1201      * where the city names are sorted:
    1202      * <pre>{@code
    1203      * ConcurrentMap<City, Set<String>> namesByCity
    1204      *   = people.stream().collect(
    1205      *     groupingByConcurrent(Person::getCity,
    1206      *                          ConcurrentSkipListMap::new,
    1207      *                          mapping(Person::getLastName,
    1208      *                                  toSet())));
    1209      * }</pre>
    1210      *
    1211      * @param <T> the type of the input elements
    1212      * @param <K> the type of the keys
    1213      * @param <A> the intermediate accumulation type of the downstream collector
    1214      * @param <D> the result type of the downstream reduction
    1215      * @param <M> the type of the resulting {@code ConcurrentMap}
    1216      * @param classifier a classifier function mapping input elements to keys
    1217      * @param downstream a {@code Collector} implementing the downstream reduction
    1218      * @param mapFactory a supplier providing a new empty {@code ConcurrentMap}
    1219      *                   into which the results will be inserted
    1220      * @return a concurrent, unordered {@code Collector} implementing the cascaded group-by operation
    1221      *
    1222      * @see #groupingByConcurrent(Function)
    1223      * @see #groupingByConcurrent(Function, Collector)
    1224      * @see #groupingBy(Function, Supplier, Collector)
    1225      */
    1226     public static <T, K, A, D, M extends ConcurrentMap<K, D>>
    1227     Collector<T, ?, M> groupingByConcurrent(Function<? super T, ? extends K> classifier,
    1228                                             Supplier<M> mapFactory,
    1229                                             Collector<? super T, A, D> downstream) {
    1230         Supplier<A> downstreamSupplier = downstream.supplier();
    1231         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
    1232         BinaryOperator<ConcurrentMap<K, A>> merger = Collectors.<K, A, ConcurrentMap<K, A>>mapMerger(downstream.combiner());
    1233         @SuppressWarnings("unchecked")
    1234         Supplier<ConcurrentMap<K, A>> mangledFactory = (Supplier<ConcurrentMap<K, A>>) mapFactory;
    1235         BiConsumer<ConcurrentMap<K, A>, T> accumulator;
    1236         if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) {
    1237             accumulator = (m, t) -> {
    1238                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
    1239                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
    1240                 downstreamAccumulator.accept(resultContainer, t);
    1241             };
    1242         }
    1243         else {
    1244             accumulator = (m, t) -> {
    1245                 K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key");
    1246                 A resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get());
    1247                 synchronized (resultContainer) {
    1248                     downstreamAccumulator.accept(resultContainer, t);
    1249                 }
    1250             };
    1251         }
    1252
    1253         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
    1254             return new CollectorImpl<>(mangledFactory, accumulator, merger, CH_CONCURRENT_ID);
    1255         }
    1256         else {
    1257             @SuppressWarnings("unchecked")
    1258             Function<A, A> downstreamFinisher = (Function<A, A>) downstream.finisher();
    1259             Function<ConcurrentMap<K, A>, M> finisher = intermediate -> {
    1260                 intermediate.replaceAll((k, v) -> downstreamFinisher.apply(v));
    1261                 @SuppressWarnings("unchecked")
    1262                 M castResult = (M) intermediate;
    1263                 return castResult;
    1264             };
    1265             return new CollectorImpl<>(mangledFactory, accumulator, merger, finisher, CH_CONCURRENT_NOID);
    1266         }
    1267     }
    1268
    1269     /**
    1270      * Returns a {@code Collector} which partitions the input elements according
    1271      * to a {@code Predicate}, and organizes them into a
    1272      * {@code Map<Boolean, List<T>>}.
    1273      *
    1274      * The returned {@code Map} always contains mappings for both
    1275      * {@code false} and {@code true} keys.
    1276      * There are no guarantees on the type, mutability,
    1277      * serializability, or thread-safety of the {@code Map} or {@code List}
    1278      * returned.
    1279      *
    1280      * @apiNote
    1281      * If a partition has no elements, its value in the result Map will be
    1282      * an empty List.
    1283      *
    1284      * @param <T> the type of the input elements
    1285      * @param predicate a predicate used for classifying input elements
    1286      * @return a {@code Collector} implementing the partitioning operation
    1287      *
    1288      * @see #partitioningBy(Predicate, Collector)
    1289      */
    1290     public static <T>
    1291     Collector<T, ?, Map<Boolean, List<T>>> partitioningBy(Predicate<? super T> predicate) {
    1292         return partitioningBy(predicate, toList());
    1293     }
    1294
    1295     /**
    1296      * Returns a {@code Collector} which partitions the input elements according
    1297      * to a {@code Predicate}, reduces the values in each partition according to
    1298      * another {@code Collector}, and organizes them into a
    1299      * {@code Map<Boolean, D>} whose values are the result of the downstream
    1300      * reduction.
    1301      *
    1302      * <p>
    1303      * The returned {@code Map} always contains mappings for both
    1304      * {@code false} and {@code true} keys.
    1305      * There are no guarantees on the type, mutability,
    1306      * serializability, or thread-safety of the {@code Map} returned.
    1307      *
    1308      * @apiNote
    1309      * If a partition has no elements, its value in the result Map will be
    1310      * obtained by calling the downstream collector's supplier function and then
    1311      * applying the finisher function.
    1312      *
    1313      * @param <T> the type of the input elements
    1314      * @param <A> the intermediate accumulation type of the downstream collector
    1315      * @param <D> the result type of the downstream reduction
    1316      * @param predicate a predicate used for classifying input elements
    1317      * @param downstream a {@code Collector} implementing the downstream
    1318      *                   reduction
    1319      * @return a {@code Collector} implementing the cascaded partitioning
    1320      *         operation
    1321      *
    1322      * @see #partitioningBy(Predicate)
    1323      */
    1324     public static <T, D, A>
    1325     Collector<T, ?, Map<Boolean, D>> partitioningBy(Predicate<? super T> predicate,
    1326                                                     Collector<? super T, A, D> downstream) {
    1327         BiConsumer<A, ? super T> downstreamAccumulator = downstream.accumulator();
    1328         BiConsumer<Partition<A>, T> accumulator = (result, t) ->
    1329                 downstreamAccumulator.accept(predicate.test(t) ? result.forTrue : result.forFalse, t);
    1330         BinaryOperator<A> op = downstream.combiner();
    1331         BinaryOperator<Partition<A>> merger = (left, right) ->
    1332                 new Partition<>(op.apply(left.forTrue, right.forTrue),
    1333                                 op.apply(left.forFalse, right.forFalse));
    1334         Supplier<Partition<A>> supplier = () ->
    1335                 new Partition<>(downstream.supplier().get(),
    1336                                 downstream.supplier().get());
    1337         if (downstream.characteristics().contains(Collector.Characteristics.IDENTITY_FINISH)) {
    1338             return new CollectorImpl<>(supplier, accumulator, merger, CH_ID);
    1339         }
    1340         else {
    1341             Function<Partition<A>, Map<Boolean, D>> finisher = par ->
    1342                     new Partition<>(downstream.finisher().apply(par.forTrue),
    1343                                     downstream.finisher().apply(par.forFalse));
    1344             return new CollectorImpl<>(supplier, accumulator, merger, finisher, CH_NOID);
    1345         }
    1346     }
    1347
    1348     /**
    1349      * Returns a {@code Collector} that accumulates elements into a
    1350      * {@code Map} whose keys and values are the result of applying the provided
    1351      * mapping functions to the input elements.
    1352      *
    1353      * <p>If the mapped keys contain duplicates (according to
    1354      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
    1355      * thrown when the collection operation is performed.  If the mapped keys
    1356      * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)}
    1357      * instead.
    1358      *
    1359      * <p>There are no guarantees on the type, mutability, serializability,
    1360      * or thread-safety of the {@code Map} returned.
    1361      *
    1362      * @apiNote
    1363      * It is common for either the key or the value to be the input elements.
    1364      * In this case, the utility method
    1365      * {@link java.util.function.Function#identity()} may be helpful.
    1366      * For example, the following produces a {@code Map} mapping
    1367      * students to their grade point average:
    1368      * <pre>{@code
    1369      * Map<Student, Double> studentToGPA
    1370      *   = students.stream().collect(
    1371      *     toMap(Function.identity(),
    1372      *           student -> computeGPA(student)));
    1373      * }</pre>
    1374      * And the following produces a {@code Map} mapping a unique identifier to
    1375      * students:
    1376      * <pre>{@code
    1377      * Map<String, Student> studentIdToStudent
    1378      *   = students.stream().collect(
    1379      *     toMap(Student::getId,
    1380      *           Function.identity()));
    1381      * }</pre>
    1382      *
    1383      * @implNote
    1384      * The returned {@code Collector} is not concurrent.  For parallel stream
    1385      * pipelines, the {@code combiner} function operates by merging the keys
    1386      * from one map into another, which can be an expensive operation.  If it is
    1387      * not required that results are inserted into the {@code Map} in encounter
    1388      * order, using {@link #toConcurrentMap(Function, Function)}
    1389      * may offer better parallel performance.
    1390      *
    1391      * @param <T> the type of the input elements
    1392      * @param <K> the output type of the key mapping function
    1393      * @param <U> the output type of the value mapping function
    1394      * @param keyMapper a mapping function to produce keys
    1395      * @param valueMapper a mapping function to produce values
    1396      * @return a {@code Collector} which collects elements into a {@code Map}
    1397      * whose keys and values are the result of applying mapping functions to
    1398      * the input elements
    1399      *
    1400      * @see #toMap(Function, Function, BinaryOperator)
    1401      * @see #toMap(Function, Function, BinaryOperator, Supplier)
    1402      * @see #toConcurrentMap(Function, Function)
    1403      */
    1404     public static <T, K, U>
    1405     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
    1406                                     Function<? super T, ? extends U> valueMapper) {
    1407         return new CollectorImpl<>(HashMap::new,
    1408                                    uniqKeysMapAccumulator(keyMapper, valueMapper),
    1409                                    uniqKeysMapMerger(),
    1410                                    CH_ID);
    1411     }
    1412
    1413     /**
    1414      * Returns a {@code Collector} that accumulates elements into a
    1415      * {@code Map} whose keys and values are the result of applying the provided
    1416      * mapping functions to the input elements.
    1417      *
    1418      * <p>If the mapped
    1419      * keys contain duplicates (according to {@link Object#equals(Object)}),
    1420      * the value mapping function is applied to each equal element, and the
    1421      * results are merged using the provided merging function.
    1422      *
    1423      * <p>There are no guarantees on the type, mutability, serializability,
    1424      * or thread-safety of the {@code Map} returned.
    1425      *
    1426      * @apiNote
    1427      * There are multiple ways to deal with collisions between multiple elements
    1428      * mapping to the same key.  The other forms of {@code toMap} simply use
    1429      * a merge function that throws unconditionally, but you can easily write
    1430      * more flexible merge policies.  For example, if you have a stream
    1431      * of {@code Person}, and you want to produce a "phone book" mapping name to
    1432      * address, but it is possible that two persons have the same name, you can
    1433      * do as follows to gracefully deal with these collisions, and produce a
    1434      * {@code Map} mapping names to a concatenated list of addresses:
    1435      * <pre>{@code
    1436      * Map<String, String> phoneBook
    1437      *   = people.stream().collect(
    1438      *     toMap(Person::getName,
    1439      *           Person::getAddress,
    1440      *           (s, a) -> s + ", " + a));
    1441      * }</pre>
    1442      *
    1443      * @implNote
    1444      * The returned {@code Collector} is not concurrent.  For parallel stream
    1445      * pipelines, the {@code combiner} function operates by merging the keys
    1446      * from one map into another, which can be an expensive operation.  If it is
    1447      * not required that results are merged into the {@code Map} in encounter
    1448      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator)}
    1449      * may offer better parallel performance.
    1450      *
    1451      * @param <T> the type of the input elements
    1452      * @param <K> the output type of the key mapping function
    1453      * @param <U> the output type of the value mapping function
    1454      * @param keyMapper a mapping function to produce keys
    1455      * @param valueMapper a mapping function to produce values
    1456      * @param mergeFunction a merge function, used to resolve collisions between
    1457      *                      values associated with the same key, as supplied
    1458      *                      to {@link Map#merge(Object, Object, BiFunction)}
    1459      * @return a {@code Collector} which collects elements into a {@code Map}
    1460      * whose keys are the result of applying a key mapping function to the input
    1461      * elements, and whose values are the result of applying a value mapping
    1462      * function to all input elements equal to the key and combining them
    1463      * using the merge function
    1464      *
    1465      * @see #toMap(Function, Function)
    1466      * @see #toMap(Function, Function, BinaryOperator, Supplier)
    1467      * @see #toConcurrentMap(Function, Function, BinaryOperator)
    1468      */
    1469     public static <T, K, U>
    1470     Collector<T, ?, Map<K,U>> toMap(Function<? super T, ? extends K> keyMapper,
    1471                                     Function<? super T, ? extends U> valueMapper,
    1472                                     BinaryOperator<U> mergeFunction) {
    1473         return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new);
    1474     }
    1475
    1476     /**
    1477      * Returns a {@code Collector} that accumulates elements into a
    1478      * {@code Map} whose keys and values are the result of applying the provided
    1479      * mapping functions to the input elements.
    1480      *
    1481      * <p>If the mapped
    1482      * keys contain duplicates (according to {@link Object#equals(Object)}),
    1483      * the value mapping function is applied to each equal element, and the
    1484      * results are merged using the provided merging function.  The {@code Map}
    1485      * is created by a provided supplier function.
    1486      *
    1487      * @implNote
    1488      * The returned {@code Collector} is not concurrent.  For parallel stream
    1489      * pipelines, the {@code combiner} function operates by merging the keys
    1490      * from one map into another, which can be an expensive operation.  If it is
    1491      * not required that results are merged into the {@code Map} in encounter
    1492      * order, using {@link #toConcurrentMap(Function, Function, BinaryOperator, Supplier)}
    1493      * may offer better parallel performance.
    1494      *
    1495      * @param <T> the type of the input elements
    1496      * @param <K> the output type of the key mapping function
    1497      * @param <U> the output type of the value mapping function
    1498      * @param <M> the type of the resulting {@code Map}
    1499      * @param keyMapper a mapping function to produce keys
    1500      * @param valueMapper a mapping function to produce values
    1501      * @param mergeFunction a merge function, used to resolve collisions between
    1502      *                      values associated with the same key, as supplied
    1503      *                      to {@link Map#merge(Object, Object, BiFunction)}
    1504      * @param mapFactory a supplier providing a new empty {@code Map}
    1505      *                   into which the results will be inserted
    1506      * @return a {@code Collector} which collects elements into a {@code Map}
    1507      * whose keys are the result of applying a key mapping function to the input
    1508      * elements, and whose values are the result of applying a value mapping
    1509      * function to all input elements equal to the key and combining them
    1510      * using the merge function
    1511      *
    1512      * @see #toMap(Function, Function)
    1513      * @see #toMap(Function, Function, BinaryOperator)
    1514      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
    1515      */
    1516     public static <T, K, U, M extends Map<K, U>>
    1517     Collector<T, ?, M> toMap(Function<? super T, ? extends K> keyMapper,
    1518                              Function<? super T, ? extends U> valueMapper,
    1519                              BinaryOperator<U> mergeFunction,
    1520                              Supplier<M> mapFactory) {
    1521         BiConsumer<M, T> accumulator
    1522                 = (map, element) -> map.merge(keyMapper.apply(element),
    1523                                               valueMapper.apply(element), mergeFunction);
    1524         return new CollectorImpl<>(mapFactory, accumulator, mapMerger(mergeFunction), CH_ID);
    1525     }
    1526
    1527     /**
    1528      * Returns a concurrent {@code Collector} that accumulates elements into a
    1529      * {@code ConcurrentMap} whose keys and values are the result of applying
    1530      * the provided mapping functions to the input elements.
    1531      *
    1532      * <p>If the mapped keys contain duplicates (according to
    1533      * {@link Object#equals(Object)}), an {@code IllegalStateException} is
    1534      * thrown when the collection operation is performed.  If the mapped keys
    1535      * may have duplicates, use
    1536      * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead.
    1537      *
    1538      * <p>There are no guarantees on the type, mutability, or serializability
    1539      * of the {@code ConcurrentMap} returned.
    1540      *
    1541      * @apiNote
    1542      * It is common for either the key or the value to be the input elements.
    1543      * In this case, the utility method
    1544      * {@link java.util.function.Function#identity()} may be helpful.
    1545      * For example, the following produces a {@code ConcurrentMap} mapping
    1546      * students to their grade point average:
    1547      * <pre>{@code
    1548      * ConcurrentMap<Student, Double> studentToGPA
    1549      *   = students.stream().collect(
    1550      *     toConcurrentMap(Function.identity(),
    1551      *                     student -> computeGPA(student)));
    1552      * }</pre>
    1553      * And the following produces a {@code ConcurrentMap} mapping a
    1554      * unique identifier to students:
    1555      * <pre>{@code
    1556      * ConcurrentMap<String, Student> studentIdToStudent
    1557      *   = students.stream().collect(
    1558      *     toConcurrentMap(Student::getId,
    1559      *                     Function.identity()));
    1560      * }</pre>
    1561      *
    1562      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1563      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1564      *
    1565      * @param <T> the type of the input elements
    1566      * @param <K> the output type of the key mapping function
    1567      * @param <U> the output type of the value mapping function
    1568      * @param keyMapper the mapping function to produce keys
    1569      * @param valueMapper the mapping function to produce values
    1570      * @return a concurrent, unordered {@code Collector} which collects elements into a
    1571      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
    1572      * function to the input elements, and whose values are the result of
    1573      * applying a value mapping function to the input elements
    1574      *
    1575      * @see #toMap(Function, Function)
    1576      * @see #toConcurrentMap(Function, Function, BinaryOperator)
    1577      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
    1578      */
    1579     public static <T, K, U>
    1580     Collector<T, ?, ConcurrentMap<K,U>> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
    1581                                                         Function<? super T, ? extends U> valueMapper) {
    1582         return new CollectorImpl<>(ConcurrentHashMap::new,
    1583                                    uniqKeysMapAccumulator(keyMapper, valueMapper),
    1584                                    uniqKeysMapMerger(),
    1585                                    CH_CONCURRENT_ID);
    1586     }
    1587
    1588     /**
    1589      * Returns a concurrent {@code Collector} that accumulates elements into a
    1590      * {@code ConcurrentMap} whose keys and values are the result of applying
    1591      * the provided mapping functions to the input elements.
    1592      *
    1593      * <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}),
    1594      * the value mapping function is applied to each equal element, and the
    1595      * results are merged using the provided merging function.
    1596      *
    1597      * <p>There are no guarantees on the type, mutability, or serializability
    1598      * of the {@code ConcurrentMap} returned.
    1599      *
    1600      * @apiNote
    1601      * There are multiple ways to deal with collisions between multiple elements
    1602      * mapping to the same key.  The other forms of {@code toConcurrentMap} simply use
    1603      * a merge function that throws unconditionally, but you can easily write
    1604      * more flexible merge policies.  For example, if you have a stream
    1605      * of {@code Person}, and you want to produce a "phone book" mapping name to
    1606      * address, but it is possible that two persons have the same name, you can
    1607      * do as follows to gracefully deal with these collisions, and produce a
    1608      * {@code ConcurrentMap} mapping names to a concatenated list of addresses:
    1609      * <pre>{@code
    1610      * ConcurrentMap<String, String> phoneBook
    1611      *   = people.stream().collect(
    1612      *     toConcurrentMap(Person::getName,
    1613      *                     Person::getAddress,
    1614      *                     (s, a) -> s + ", " + a));
    1615      * }</pre>
    1616      *
    1617      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1618      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1619      *
    1620      * @param <T> the type of the input elements
    1621      * @param <K> the output type of the key mapping function
    1622      * @param <U> the output type of the value mapping function
    1623      * @param keyMapper a mapping function to produce keys
    1624      * @param valueMapper a mapping function to produce values
    1625      * @param mergeFunction a merge function, used to resolve collisions between
    1626      *                      values associated with the same key, as supplied
    1627      *                      to {@link Map#merge(Object, Object, BiFunction)}
    1628      * @return a concurrent, unordered {@code Collector} which collects elements into a
    1629      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
    1630      * function to the input elements, and whose values are the result of
    1631      * applying a value mapping function to all input elements equal to the key
    1632      * and combining them using the merge function
    1633      *
    1634      * @see #toConcurrentMap(Function, Function)
    1635      * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier)
    1636      * @see #toMap(Function, Function, BinaryOperator)
    1637      */
    1638     public static <T, K, U>
    1639     Collector<T, ?, ConcurrentMap<K,U>>
    1640     toConcurrentMap(Function<? super T, ? extends K> keyMapper,
    1641                     Function<? super T, ? extends U> valueMapper,
    1642                     BinaryOperator<U> mergeFunction) {
    1643         return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new);
    1644     }
    1645
    1646     /**
    1647      * Returns a concurrent {@code Collector} that accumulates elements into a
    1648      * {@code ConcurrentMap} whose keys and values are the result of applying
    1649      * the provided mapping functions to the input elements.
    1650      *
    1651      * <p>If the mapped keys contain duplicates (according to {@link Object#equals(Object)}),
    1652      * the value mapping function is applied to each equal element, and the
    1653      * results are merged using the provided merging function.  The
    1654      * {@code ConcurrentMap} is created by a provided supplier function.
    1655      *
    1656      * <p>This is a {@link Collector.Characteristics#CONCURRENT concurrent} and
    1657      * {@link Collector.Characteristics#UNORDERED unordered} Collector.
    1658      *
    1659      * @param <T> the type of the input elements
    1660      * @param <K> the output type of the key mapping function
    1661      * @param <U> the output type of the value mapping function
    1662      * @param <M> the type of the resulting {@code ConcurrentMap}
    1663      * @param keyMapper a mapping function to produce keys
    1664      * @param valueMapper a mapping function to produce values
    1665      * @param mergeFunction a merge function, used to resolve collisions between
    1666      *                      values associated with the same key, as supplied
    1667      *                      to {@link Map#merge(Object, Object, BiFunction)}
    1668      * @param mapFactory a supplier providing a new empty {@code ConcurrentMap}
    1669      *                   into which the results will be inserted
    1670      * @return a concurrent, unordered {@code Collector} which collects elements into a
    1671      * {@code ConcurrentMap} whose keys are the result of applying a key mapping
    1672      * function to the input elements, and whose values are the result of
    1673      * applying a value mapping function to all input elements equal to the key
    1674      * and combining them using the merge function
    1675      *
    1676      * @see #toConcurrentMap(Function, Function)
    1677      * @see #toConcurrentMap(Function, Function, BinaryOperator)
    1678      * @see #toMap(Function, Function, BinaryOperator, Supplier)
    1679      */
    1680     public static <T, K, U, M extends ConcurrentMap<K, U>>
    1681     Collector<T, ?, M> toConcurrentMap(Function<? super T, ? extends K> keyMapper,
    1682                                        Function<? super T, ? extends U> valueMapper,
    1683                                        BinaryOperator<U> mergeFunction,
    1684                                        Supplier<M> mapFactory) {
    1685         BiConsumer<M, T> accumulator
    1686                 = (map, element) -> map.merge(keyMapper.apply(element),
    1687                                               valueMapper.apply(element), mergeFunction);
    1688         return new CollectorImpl<>(mapFactory, accumulator, mapMerger(mergeFunction), CH_CONCURRENT_ID);
    1689     }
    1690
    1691     /**
    1692      * Returns a {@code Collector} which applies an {@code int}-producing
    1693      * mapping function to each input element, and returns summary statistics
    1694      * for the resulting values.
    1695      *
    1696      * @param <T> the type of the input elements
    1697      * @param mapper a mapping function to apply to each element
    1698      * @return a {@code Collector} implementing the summary-statistics reduction
    1699      *
    1700      * @see #summarizingDouble(ToDoubleFunction)
    1701      * @see #summarizingLong(ToLongFunction)
    1702      */
    1703     public static <T>
    1704     Collector<T, ?, IntSummaryStatistics> summarizingInt(ToIntFunction<? super T> mapper) {
    1705         return new CollectorImpl<T, IntSummaryStatistics, IntSummaryStatistics>(
    1706                 IntSummaryStatistics::new,
    1707                 (r, t) -> r.accept(mapper.applyAsInt(t)),
    1708                 (l, r) -> { l.combine(r); return l; }, CH_ID);
    1709     }
    1710
    1711     /**
    1712      * Returns a {@code Collector} which applies an {@code long}-producing
    1713      * mapping function to each input element, and returns summary statistics
    1714      * for the resulting values.
    1715      *
    1716      * @param <T> the type of the input elements
    1717      * @param mapper the mapping function to apply to each element
    1718      * @return a {@code Collector} implementing the summary-statistics reduction
    1719      *
    1720      * @see #summarizingDouble(ToDoubleFunction)
    1721      * @see #summarizingInt(ToIntFunction)
    1722      */
    1723     public static <T>
    1724     Collector<T, ?, LongSummaryStatistics> summarizingLong(ToLongFunction<? super T> mapper) {
    1725         return new CollectorImpl<T, LongSummaryStatistics, LongSummaryStatistics>(
    1726                 LongSummaryStatistics::new,
    1727                 (r, t) -> r.accept(mapper.applyAsLong(t)),
    1728                 (l, r) -> { l.combine(r); return l; }, CH_ID);
    1729     }
    1730
    1731     /**
    1732      * Returns a {@code Collector} which applies an {@code double}-producing
    1733      * mapping function to each input element, and returns summary statistics
    1734      * for the resulting values.
    1735      *
    1736      * @param <T> the type of the input elements
    1737      * @param mapper a mapping function to apply to each element
    1738      * @return a {@code Collector} implementing the summary-statistics reduction
    1739      *
    1740      * @see #summarizingLong(ToLongFunction)
    1741      * @see #summarizingInt(ToIntFunction)
    1742      */
    1743     public static <T>
    1744     Collector<T, ?, DoubleSummaryStatistics> summarizingDouble(ToDoubleFunction<? super T> mapper) {
    1745         return new CollectorImpl<T, DoubleSummaryStatistics, DoubleSummaryStatistics>(
    1746                 DoubleSummaryStatistics::new,
    1747                 (r, t) -> r.accept(mapper.applyAsDouble(t)),
    1748                 (l, r) -> { l.combine(r); return l; }, CH_ID);
    1749     }
    1750
    1751     /**
    1752      * Implementation class used by partitioningBy.
    1753      */
    1754     private static final class Partition<T>
    1755             extends AbstractMap<Boolean, T>
    1756             implements Map<Boolean, T> {
    1757         final T forTrue;
    1758         final T forFalse;
    1759
    1760         Partition(T forTrue, T forFalse) {
    1761             this.forTrue = forTrue;
    1762             this.forFalse = forFalse;
    1763         }
    1764
    1765         @Override
    1766         public Set<Map.Entry<Boolean, T>> entrySet() {
    1767             return new AbstractSet<>() {
    1768                 @Override
    1769                 public Iterator<Map.Entry<Boolean, T>> iterator() {
    1770                     Map.Entry<Boolean, T> falseEntry = new SimpleImmutableEntry<>(false, forFalse);
    1771                     Map.Entry<Boolean, T> trueEntry = new SimpleImmutableEntry<>(true, forTrue);
    1772                     return List.of(falseEntry, trueEntry).iterator();
    1773                 }
    1774
    1775                 @Override
    1776                 public int size() {
    1777                     return 2;
    1778                 }
    1779             };
    1780         }
    1781     }
    1782 }