/* * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.util.stream; import java.util.AbstractMap; import java.util.AbstractSet; import java.util.ArrayList; import java.util.Collection; import java.util.Collections; import java.util.Comparator; import java.util.DoubleSummaryStatistics; import java.util.EnumSet; import java.util.HashMap; import java.util.HashSet; import java.util.IntSummaryStatistics; import java.util.Iterator; import java.util.List; import java.util.LongSummaryStatistics; import java.util.Map; import java.util.NoSuchElementException; import java.util.Objects; import java.util.Set; import java.util.StringJoiner; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; import java.util.function.BiFunction; import java.util.function.BinaryOperator; import java.util.function.Function; import java.util.function.Predicate; import java.util.function.Supplier; import java.util.function.ToDoubleFunction; import java.util.function.ToIntFunction; import java.util.function.ToLongFunction; /** * Implementations of {@link Collector} that implement various useful reduction * operations, such as accumulating elements into collections, summarizing * elements according to various criteria, etc. * *

The following are examples of using the predefined {@code Collector} * implementations in {@link Collectors} with the {@code Stream} API to perform * mutable reduction tasks: * *

{@code
 *     // Accumulate elements into a List
 *     List list = people.collect(Collectors.toList());
 *
 *     // Accumulate elements into a TreeSet
 *     List list = people.collect(Collectors.toCollection(TreeSet::new));
 *
 *     // Convert elements to strings and concatenate them, separated by commas
 *     String joined = stream.map(Object::toString)
 *                           .collect(Collectors.toStringJoiner(", "))
 *                           .toString();
 *
 *     // Find highest-paid employee
 *     Employee highestPaid = employees.stream()
 *                                     .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)));
 *
 *     // Group employees by department
 *     Map> byDept
 *         = employees.stream()
 *                    .collect(Collectors.groupingBy(Employee::getDepartment));
 *
 *     // Find highest-paid employee by department
 *     Map highestPaidByDept
 *         = employees.stream()
 *                    .collect(Collectors.groupingBy(Employee::getDepartment,
 *                                                   Collectors.maxBy(Comparator.comparing(Employee::getSalary))));
 *
 *     // Partition students into passing and failing
 *     Map> passingFailing =
 *         students.stream()
 *                 .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);
 *
 * }
* * TODO explanation of parallel collection * * @since 1.8 */ public final class Collectors { private static final Set CH_CONCURRENT = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.CONCURRENT, Collector.Characteristics.STRICTLY_MUTATIVE, Collector.Characteristics.UNORDERED)); private static final Set CH_STRICT = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.STRICTLY_MUTATIVE)); private static final Set CH_STRICT_UNORDERED = Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.STRICTLY_MUTATIVE, Collector.Characteristics.UNORDERED)); private Collectors() { } /** * Returns a merge function, suitable for use in * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or * {@link #toMap(Function, Function, BinaryOperator) toMap()}, which always * throws {@code IllegalStateException}. This can be used to enforce the * assumption that the elements being collected are distinct. * * @param the type of input arguments to the merge function * @return a merge function which always throw {@code IllegalStateException} * * @see #firstWinsMerger() * @see #lastWinsMerger() */ public static BinaryOperator throwingMerger() { return (u,v) -> { throw new IllegalStateException(String.format("Duplicate key %s", u)); }; } /** * Returns a merge function, suitable for use in * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or * {@link #toMap(Function, Function, BinaryOperator) toMap()}, * which implements a "first wins" policy. * * @param the type of input arguments to the merge function * @return a merge function which always returns its first argument * @see #lastWinsMerger() * @see #throwingMerger() */ public static BinaryOperator firstWinsMerger() { return (u,v) -> u; } /** * Returns a merge function, suitable for use in * {@link Map#merge(Object, Object, BiFunction) Map.merge()} or * {@link #toMap(Function, Function, BinaryOperator) toMap()}, * which implements a "last wins" policy. * * @param the type of input arguments to the merge function * @return a merge function which always returns its second argument * @see #firstWinsMerger() * @see #throwingMerger() */ public static BinaryOperator lastWinsMerger() { return (u,v) -> v; } /** * Simple implementation class for {@code Collector}. * * @param the type of elements to be collected * @param the type of the result */ private static final class CollectorImpl implements Collector { private final Supplier resultSupplier; private final BiFunction accumulator; private final BinaryOperator combiner; private final Set characteristics; CollectorImpl(Supplier resultSupplier, BiFunction accumulator, BinaryOperator combiner, Set characteristics) { this.resultSupplier = resultSupplier; this.accumulator = accumulator; this.combiner = combiner; this.characteristics = characteristics; } CollectorImpl(Supplier resultSupplier, BiFunction accumulator, BinaryOperator combiner) { this(resultSupplier, accumulator, combiner, Collections.emptySet()); } @Override public BiFunction accumulator() { return accumulator; } @Override public Supplier resultSupplier() { return resultSupplier; } @Override public BinaryOperator combiner() { return combiner; } @Override public Set characteristics() { return characteristics; } } /** * Returns a {@code Collector} that accumulates the input elements into a * new {@code Collection}, in encounter order. The {@code Collection} is * created by the provided factory. * * @param the type of the input elements * @param the type of the resulting {@code Collection} * @param collectionFactory a {@code Supplier} which returns a new, empty * {@code Collection} of the appropriate type * @return a {@code Collector} which collects all the input elements into a * {@code Collection}, in encounter order */ public static > Collector toCollection(Supplier collectionFactory) { return new CollectorImpl<>(collectionFactory, (r, t) -> { r.add(t); return r; }, (r1, r2) -> { r1.addAll(r2); return r1; }, CH_STRICT); } /** * Returns a {@code Collector} that accumulates the input elements into a * new {@code List}. There are no guarantees on the type, mutability, * serializability, or thread-safety of the {@code List} returned. * * @param the type of the input elements * @return a {@code Collector} which collects all the input elements into a * {@code List}, in encounter order */ public static Collector> toList() { BiFunction, T, List> accumulator = (list, t) -> { switch (list.size()) { case 0: return Collections.singletonList(t); case 1: List newList = new ArrayList<>(); newList.add(list.get(0)); newList.add(t); return newList; default: list.add(t); return list; } }; BinaryOperator> combiner = (left, right) -> { switch (left.size()) { case 0: return right; case 1: List newList = new ArrayList<>(left.size() + right.size()); newList.addAll(left); newList.addAll(right); return newList; default: left.addAll(right); return left; } }; return new CollectorImpl<>(Collections::emptyList, accumulator, combiner); } /** * Returns a {@code Collector} that accumulates the input elements into a * new {@code Set}. There are no guarantees on the type, mutability, * serializability, or thread-safety of the {@code Set} returned. * *

This is an {@link Collector.Characteristics#UNORDERED unordered} * Collector. * * @param the type of the input elements * @return a {@code Collector} which collects all the input elements into a * {@code Set} */ public static Collector> toSet() { return new CollectorImpl<>((Supplier>) HashSet::new, (r, t) -> { r.add(t); return r; }, (r1, r2) -> { r1.addAll(r2); return r1; }, CH_STRICT_UNORDERED); } /** * Returns a {@code Collector} that concatenates the input elements into a * new {@link StringBuilder}. * * @return a {@code Collector} which collects String elements into a * {@code StringBuilder}, in encounter order */ public static Collector toStringBuilder() { return new CollectorImpl<>(StringBuilder::new, (r, t) -> { r.append(t); return r; }, (r1, r2) -> { r1.append(r2); return r1; }, CH_STRICT); } /** * Returns a {@code Collector} that concatenates the input elements into a * new {@link StringJoiner}, using the specified delimiter. * * @param delimiter the delimiter to be used between each element * @return A {@code Collector} which collects String elements into a * {@code StringJoiner}, in encounter order */ public static Collector toStringJoiner(CharSequence delimiter) { BinaryOperator merger = (sj, other) -> { if (other.length() > 0) sj.add(other.toString()); return sj; }; return new CollectorImpl<>(() -> new StringJoiner(delimiter), (r, t) -> { r.add(t); return r; }, merger, CH_STRICT); } /** * {@code BinaryOperator} that merges the contents of its right * argument into its left argument, using the provided merge function to * handle duplicate keys. * * @param type of the map keys * @param type of the map values * @param type of the map * @param mergeFunction A merge function suitable for * {@link Map#merge(Object, Object, BiFunction) Map.merge()} * @return a merge function for two maps */ private static > BinaryOperator mapMerger(BinaryOperator mergeFunction) { return (m1, m2) -> { for (Map.Entry e : m2.entrySet()) m1.merge(e.getKey(), e.getValue(), mergeFunction); return m1; }; } /** * Adapts a {@code Collector} to a {@code Collector} by applying * a mapping function to each input element before accumulation. * * @apiNote * The {@code mapping()} collectors are most useful when used in a * multi-level reduction, downstream of {@code groupingBy} or * {@code partitioningBy}. For example, given a stream of * {@code Person}, to accumulate the set of last names in each city: *

{@code
     *     Map> lastNamesByCity
     *         = people.stream().collect(groupingBy(Person::getCity,
     *                                              mapping(Person::getLastName, toSet())));
     * }
* * @param the type of the input elements * @param type of elements accepted by downstream collector * @param result type of collector * @param mapper a function to be applied to the input elements * @param downstream a collector which will accept mapped values * @return a collector which applies the mapping function to the input * elements and provides the mapped results to the downstream collector */ public static Collector mapping(Function mapper, Collector downstream) { BiFunction downstreamAccumulator = downstream.accumulator(); return new CollectorImpl<>(downstream.resultSupplier(), (r, t) -> downstreamAccumulator.apply(r, mapper.apply(t)), downstream.combiner(), downstream.characteristics()); } /** * Returns a {@code Collector} that counts the number of input * elements. * * @implSpec * This produces a result equivalent to: *
{@code
     *     reducing(0L, e -> 1L, Long::sum)
     * }
* * @param the type of the input elements * @return a {@code Collector} that counts the input elements */ public static Collector counting() { return reducing(0L, e -> 1L, Long::sum); } /** * Returns a {@code Collector} that produces the minimal element * according to a given {@code Comparator}. * * @implSpec * This produces a result equivalent to: *
{@code
     *     reducing(BinaryOperator.minBy(comparator))
     * }
* * @param the type of the input elements * @param comparator a {@code Comparator} for comparing elements * @return a {@code Collector} that produces the minimal value */ public static Collector minBy(Comparator comparator) { return reducing(BinaryOperator.minBy(comparator)); } /** * Returns a {@code Collector} that produces the maximal element * according to a given {@code Comparator}. * * @implSpec * This produces a result equivalent to: *
{@code
     *     reducing(BinaryOperator.maxBy(comparator))
     * }
* * @param the type of the input elements * @param comparator a {@code Comparator} for comparing elements * @return a {@code Collector} that produces the maximal value */ public static Collector maxBy(Comparator comparator) { return reducing(BinaryOperator.maxBy(comparator)); } /** * Returns a {@code Collector} that produces the sum of a * long-valued function applied to the input element. * * @implSpec * This produces a result equivalent to: *
{@code
     *     reducing(0L, mapper, Long::sum)
     * }
* * @param the type of the input elements * @param mapper a function extracting the property to be summed * @return a {@code Collector} that produces the sum of a derived property */ public static Collector sumBy(Function mapper) { return reducing(0L, mapper, Long::sum); } /** * Returns a {@code Collector} which performs a reduction of its * input elements under a specified {@code BinaryOperator}. * * @apiNote * The {@code reducing()} collectors are most useful when used in a * multi-level reduction, downstream of {@code groupingBy} or * {@code partitioningBy}. To perform a simple reduction on a stream, * use {@link Stream#reduce(BinaryOperator)} instead. * * @param element type for the input and output of the reduction * @param identity the identity value for the reduction (also, the value * that is returned when there are no input elements) * @param op a {@code BinaryOperator} used to reduce the input elements * @return a {@code Collector} which implements the reduction operation * * @see #reducing(BinaryOperator) * @see #reducing(Object, Function, BinaryOperator) */ public static Collector reducing(T identity, BinaryOperator op) { return new CollectorImpl<>(() -> identity, (r, t) -> (r == null ? t : op.apply(r, t)), op); } /** * Returns a {@code Collector} which performs a reduction of its * input elements under a specified {@code BinaryOperator}. * * @apiNote * The {@code reducing()} collectors are most useful when used in a * multi-level reduction, downstream of {@code groupingBy} or * {@code partitioningBy}. To perform a simple reduction on a stream, * use {@link Stream#reduce(BinaryOperator)} instead. * *

For example, given a stream of {@code Person}, to calculate tallest * person in each city: *

{@code
     *     Comparator byHeight = Comparator.comparing(Person::getHeight);
     *     BinaryOperator tallerOf = BinaryOperator.greaterOf(byHeight);
     *     Map tallestByCity
     *         = people.stream().collect(groupingBy(Person::getCity, reducing(tallerOf)));
     * }
* * @implSpec * The default implementation is equivalent to: *
{@code
     *     reducing(null, op);
     * }
* * @param element type for the input and output of the reduction * @param op a {@code BinaryOperator} used to reduce the input elements * @return a {@code Collector} which implements the reduction operation * * @see #reducing(Object, BinaryOperator) * @see #reducing(Object, Function, BinaryOperator) */ public static Collector reducing(BinaryOperator op) { return reducing(null, op); } /** * Returns a {@code Collector} which performs a reduction of its * input elements under a specified mapping function and * {@code BinaryOperator}. This is a generalization of * {@link #reducing(Object, BinaryOperator)} which allows a transformation * of the elements before reduction. * * @apiNote * The {@code reducing()} collectors are most useful when used in a * multi-level reduction, downstream of {@code groupingBy} or * {@code partitioningBy}. To perform a simple reduction on a stream, * use {@link Stream#reduce(BinaryOperator)} instead. * *

For example, given a stream of {@code Person}, to calculate the longest * last name of residents in each city: *

{@code
     *     Comparator byLength = Comparator.comparing(String::length);
     *     BinaryOperator longerOf = BinaryOperator.greaterOf(byLength);
     *     Map longestLastNameByCity
     *         = people.stream().collect(groupingBy(Person::getCity,
     *                                              reducing(Person::getLastName, longerOf)));
     * }
* * @param the type of the input elements * @param the type of the mapped values * @param identity the identity value for the reduction (also, the value * that is returned when there are no input elements) * @param mapper a mapping function to apply to each input value * @param op a {@code BinaryOperator} used to reduce the mapped values * @return a {@code Collector} implementing the map-reduce operation * * @see #reducing(Object, BinaryOperator) * @see #reducing(BinaryOperator) */ public static Collector reducing(U identity, Function mapper, BinaryOperator op) { return new CollectorImpl<>(() -> identity, (r, t) -> (r == null ? mapper.apply(t) : op.apply(r, mapper.apply(t))), op); } /** * Returns a {@code Collector} implementing a "group by" operation on * input elements of type {@code T}, grouping elements according to a * classification function. * *

The classification function maps elements to some key type {@code K}. * The collector produces a {@code Map>} whose keys are the * values resulting from applying the classification function to the input * elements, and whose corresponding values are {@code List}s containing the * input elements which map to the associated key under the classification * function. * *

There are no guarantees on the type, mutability, serializability, or * thread-safety of the {@code Map} or {@code List} objects returned. * @implSpec * This produces a result similar to: *

{@code
     *     groupingBy(classifier, toList());
     * }
* * @param the type of the input elements * @param the type of the keys * @param classifier the classifier function mapping input elements to keys * @return a {@code Collector} implementing the group-by operation * * @see #groupingBy(Function, Collector) * @see #groupingBy(Function, Supplier, Collector) * @see #groupingByConcurrent(Function) */ public static Collector>> groupingBy(Function classifier) { return groupingBy(classifier, HashMap::new, toList()); } /** * Returns a {@code Collector} implementing a cascaded "group by" operation * on input elements of type {@code T}, grouping elements according to a * classification function, and then performing a reduction operation on * the values associated with a given key using the specified downstream * {@code Collector}. * *

The classification function maps elements to some key type {@code K}. * The downstream collector operates on elements of type {@code T} and * produces a result of type {@code D}. The resulting collector produces a * {@code Map}. * *

There are no guarantees on the type, mutability, * serializability, or thread-safety of the {@code Map} returned. * *

For example, to compute the set of last names of people in each city: *

{@code
     *     Map> namesByCity
     *         = people.stream().collect(groupingBy(Person::getCity,
     *                                              mapping(Person::getLastName, toSet())));
     * }
* * @param the type of the input elements * @param the type of the keys * @param the result type of the downstream reduction * @param classifier a classifier function mapping input elements to keys * @param downstream a {@code Collector} implementing the downstream reduction * @return a {@code Collector} implementing the cascaded group-by operation * @see #groupingBy(Function) * * @see #groupingBy(Function, Supplier, Collector) * @see #groupingByConcurrent(Function, Collector) */ public static Collector> groupingBy(Function classifier, Collector downstream) { return groupingBy(classifier, HashMap::new, downstream); } /** * Returns a {@code Collector} implementing a cascaded "group by" operation * on input elements of type {@code T}, grouping elements according to a * classification function, and then performing a reduction operation on * the values associated with a given key using the specified downstream * {@code Collector}. The {@code Map} produced by the Collector is created * with the supplied factory function. * *

The classification function maps elements to some key type {@code K}. * The downstream collector operates on elements of type {@code T} and * produces a result of type {@code D}. The resulting collector produces a * {@code Map}. * *

For example, to compute the set of last names of people in each city, * where the city names are sorted: *

{@code
     *     Map> namesByCity
     *         = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
     *                                              mapping(Person::getLastName, toSet())));
     * }
* * @param the type of the input elements * @param the type of the keys * @param the result type of the downstream reduction * @param the type of the resulting {@code Map} * @param classifier a classifier function mapping input elements to keys * @param downstream a {@code Collector} implementing the downstream reduction * @param mapFactory a function which, when called, produces a new empty * {@code Map} of the desired type * @return a {@code Collector} implementing the cascaded group-by operation * * @see #groupingBy(Function, Collector) * @see #groupingBy(Function) * @see #groupingByConcurrent(Function, Supplier, Collector) */ public static > Collector groupingBy(Function classifier, Supplier mapFactory, Collector downstream) { Supplier downstreamSupplier = downstream.resultSupplier(); BiFunction downstreamAccumulator = downstream.accumulator(); BiFunction accumulator = (m, t) -> { K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key"); D oldContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get()); D newContainer = downstreamAccumulator.apply(oldContainer, t); if (newContainer != oldContainer) m.put(key, newContainer); return m; }; return new CollectorImpl<>(mapFactory, accumulator, mapMerger(downstream.combiner()), CH_STRICT); } /** * Returns a {@code Collector} implementing a concurrent "group by" * operation on input elements of type {@code T}, grouping elements * according to a classification function. * *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * *

The classification function maps elements to some key type {@code K}. * The collector produces a {@code ConcurrentMap>} whose keys are the * values resulting from applying the classification function to the input * elements, and whose corresponding values are {@code List}s containing the * input elements which map to the associated key under the classification * function. * *

There are no guarantees on the type, mutability, or serializability * of the {@code Map} or {@code List} objects returned, or of the * thread-safety of the {@code List} objects returned. * @implSpec * This produces a result similar to: *

{@code
     *     groupingByConcurrent(classifier, toList());
     * }
* * @param the type of the input elements * @param the type of the keys * @param classifier a classifier function mapping input elements to keys * @return a {@code Collector} implementing the group-by operation * * @see #groupingBy(Function) * @see #groupingByConcurrent(Function, Collector) * @see #groupingByConcurrent(Function, Supplier, Collector) */ public static Collector>> groupingByConcurrent(Function classifier) { return groupingByConcurrent(classifier, ConcurrentHashMap::new, toList()); } /** * Returns a {@code Collector} implementing a concurrent cascaded "group by" * operation on input elements of type {@code T}, grouping elements * according to a classification function, and then performing a reduction * operation on the values associated with a given key using the specified * downstream {@code Collector}. * *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * *

The classification function maps elements to some key type {@code K}. * The downstream collector operates on elements of type {@code T} and * produces a result of type {@code D}. The resulting collector produces a * {@code Map}. * *

For example, to compute the set of last names of people in each city, * where the city names are sorted: *

{@code
     *     ConcurrentMap> namesByCity
     *         = people.stream().collect(groupingByConcurrent(Person::getCity, TreeMap::new,
     *                                                        mapping(Person::getLastName, toSet())));
     * }
* * @param the type of the input elements * @param the type of the keys * @param the result type of the downstream reduction * @param classifier a classifier function mapping input elements to keys * @param downstream a {@code Collector} implementing the downstream reduction * @return a {@code Collector} implementing the cascaded group-by operation * * @see #groupingBy(Function, Collector) * @see #groupingByConcurrent(Function) * @see #groupingByConcurrent(Function, Supplier, Collector) */ public static Collector> groupingByConcurrent(Function classifier, Collector downstream) { return groupingByConcurrent(classifier, ConcurrentHashMap::new, downstream); } /** * Returns a concurrent {@code Collector} implementing a cascaded "group by" * operation on input elements of type {@code T}, grouping elements * according to a classification function, and then performing a reduction * operation on the values associated with a given key using the specified * downstream {@code Collector}. The {@code ConcurrentMap} produced by the * Collector is created with the supplied factory function. * *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * *

The classification function maps elements to some key type {@code K}. * The downstream collector operates on elements of type {@code T} and * produces a result of type {@code D}. The resulting collector produces a * {@code Map}. * *

For example, to compute the set of last names of people in each city, * where the city names are sorted: *

{@code
     *     ConcurrentMap> namesByCity
     *         = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
     *                                              mapping(Person::getLastName, toSet())));
     * }
* * * @param the type of the input elements * @param the type of the keys * @param the result type of the downstream reduction * @param the type of the resulting {@code ConcurrentMap} * @param classifier a classifier function mapping input elements to keys * @param downstream a {@code Collector} implementing the downstream reduction * @param mapFactory a function which, when called, produces a new empty * {@code ConcurrentMap} of the desired type * @return a {@code Collector} implementing the cascaded group-by operation * * @see #groupingByConcurrent(Function) * @see #groupingByConcurrent(Function, Collector) * @see #groupingBy(Function, Supplier, Collector) */ public static > Collector groupingByConcurrent(Function classifier, Supplier mapFactory, Collector downstream) { Supplier downstreamSupplier = downstream.resultSupplier(); BiFunction downstreamAccumulator = downstream.accumulator(); BinaryOperator combiner = mapMerger(downstream.combiner()); if (downstream.characteristics().contains(Collector.Characteristics.CONCURRENT)) { BiFunction accumulator = (m, t) -> { K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key"); downstreamAccumulator.apply(m.computeIfAbsent(key, k -> downstreamSupplier.get()), t); return m; }; return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT); } else if (downstream.characteristics().contains(Collector.Characteristics.STRICTLY_MUTATIVE)) { BiFunction accumulator = (m, t) -> { K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key"); D resultContainer = m.computeIfAbsent(key, k -> downstreamSupplier.get()); synchronized (resultContainer) { downstreamAccumulator.apply(resultContainer, t); } return m; }; return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT); } else { BiFunction accumulator = (m, t) -> { K key = Objects.requireNonNull(classifier.apply(t), "element cannot be mapped to a null key"); do { D oldResult = m.computeIfAbsent(key, k -> downstreamSupplier.get()); if (oldResult == null) { if (m.putIfAbsent(key, downstreamAccumulator.apply(null, t)) == null) return m; } else { synchronized (oldResult) { if (m.get(key) != oldResult) continue; D newResult = downstreamAccumulator.apply(oldResult, t); if (oldResult != newResult) m.put(key, newResult); return m; } } } while (true); }; return new CollectorImpl<>(mapFactory, accumulator, combiner, CH_CONCURRENT); } } /** * Returns a {@code Collector} which partitions the input elements according * to a {@code Predicate}, and organizes them into a * {@code Map>}. * * There are no guarantees on the type, mutability, * serializability, or thread-safety of the {@code Map} returned. * * @param the type of the input elements * @param predicate a predicate used for classifying input elements * @return a {@code Collector} implementing the partitioning operation * * @see #partitioningBy(Predicate, Collector) */ public static Collector>> partitioningBy(Predicate predicate) { return partitioningBy(predicate, toList()); } /** * Returns a {@code Collector} which partitions the input elements according * to a {@code Predicate}, reduces the values in each partition according to * another {@code Collector}, and organizes them into a * {@code Map} whose values are the result of the downstream * reduction. * *

There are no guarantees on the type, mutability, * serializability, or thread-safety of the {@code Map} returned. * * @param the type of the input elements * @param the result type of the downstream reduction * @param predicate a predicate used for classifying input elements * @param downstream a {@code Collector} implementing the downstream * reduction * @return a {@code Collector} implementing the cascaded partitioning * operation * * @see #partitioningBy(Predicate) */ public static Collector> partitioningBy(Predicate predicate, Collector downstream) { BiFunction downstreamAccumulator = downstream.accumulator(); BiFunction, T, Map> accumulator = (result, t) -> { Partition asPartition = ((Partition) result); if (predicate.test(t)) { D newResult = downstreamAccumulator.apply(asPartition.forTrue, t); if (newResult != asPartition.forTrue) asPartition.forTrue = newResult; } else { D newResult = downstreamAccumulator.apply(asPartition.forFalse, t); if (newResult != asPartition.forFalse) asPartition.forFalse = newResult; } return result; }; return new CollectorImpl<>(() -> new Partition<>(downstream.resultSupplier().get(), downstream.resultSupplier().get()), accumulator, partitionMerger(downstream.combiner()), CH_STRICT); } /** * Merge function for two partitions, given a merge function for the * elements. */ private static BinaryOperator> partitionMerger(BinaryOperator op) { return (m1, m2) -> { Partition left = (Partition) m1; Partition right = (Partition) m2; if (left.forFalse == null) left.forFalse = right.forFalse; else if (right.forFalse != null) left.forFalse = op.apply(left.forFalse, right.forFalse); if (left.forTrue == null) left.forTrue = right.forTrue; else if (right.forTrue != null) left.forTrue = op.apply(left.forTrue, right.forTrue); return left; }; } /** * Accumulate elements into a {@code Map} whose keys and values are the * result of applying mapping functions to the input elements. * If the mapped keys contains duplicates (according to * {@link Object#equals(Object)}), an {@code IllegalStateException} is * thrown when the collection operation is performed. If the mapped keys * may have duplicates, use {@link #toMap(Function, Function, BinaryOperator)} * instead. * * @apiNote * It is common for either the key or the value to be the input elements. * In this case, the utility method * {@link java.util.function.Function#identity()} may be helpful. * For example, the following produces a {@code Map} mapping * students to their grade point average: *

{@code
     *     Map studentToGPA
     *         students.stream().collect(toMap(Functions.identity(),
     *                                         student -> computeGPA(student)));
     * }
* And the following produces a {@code Map} mapping a unique identifier to * students: *
{@code
     *     Map studentIdToStudent
     *         students.stream().collect(toMap(Student::getId,
     *                                         Functions.identity());
     * }
* * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param keyMapper a mapping function to produce keys * @param valueMapper a mapping function to produce values * @return a {@code Collector} which collects elements into a {@code Map} * whose keys and values are the result of applying mapping functions to * the input elements * * @see #toMap(Function, Function, BinaryOperator) * @see #toMap(Function, Function, BinaryOperator, Supplier) * @see #toConcurrentMap(Function, Function) */ public static Collector> toMap(Function keyMapper, Function valueMapper) { return toMap(keyMapper, valueMapper, throwingMerger(), HashMap::new); } /** * Accumulate elements into a {@code Map} whose keys and values are the * result of applying mapping functions to the input elements. If the mapped * keys contains duplicates (according to {@link Object#equals(Object)}), * the value mapping function is applied to each equal element, and the * results are merged using the provided merging function. * * @apiNote * There are multiple ways to deal with collisions between multiple elements * mapping to the same key. There are some predefined merging functions, * such as {@link #throwingMerger()}, {@link #firstWinsMerger()}, and * {@link #lastWinsMerger()}, that implement common policies, or you can * implement custom policies easily. For example, if you have a stream * of {@code Person}, and you want to produce a "phone book" mapping name to * address, but it is possible that two persons have the same name, you can * do as follows to gracefully deals with these collisions, and produce a * {@code Map} mapping names to a concatenated list of addresses: *
{@code
     *     Map phoneBook
     *         people.stream().collect(toMap(Person::getName,
     *                                       Person::getAddress,
     *                                       (s, a) -> s + ", " + a));
     * }
* * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param keyMapper a mapping function to produce keys * @param valueMapper a mapping function to produce values * @param mergeFunction a merge function, used to resolve collisions between * values associated with the same key, as supplied * to {@link Map#merge(Object, Object, BiFunction)} * @return a {@code Collector} which collects elements into a {@code Map} * whose keys are the result of applying a key mapping function to the input * elements, and whose values are the result of applying a value mapping * function to all input elements equal to the key and combining them * using the merge function * * @see #toMap(Function, Function) * @see #toMap(Function, Function, BinaryOperator, Supplier) * @see #toConcurrentMap(Function, Function, BinaryOperator) */ public static Collector> toMap(Function keyMapper, Function valueMapper, BinaryOperator mergeFunction) { return toMap(keyMapper, valueMapper, mergeFunction, HashMap::new); } /** * Accumulate elements into a {@code Map} whose keys and values are the * result of applying mapping functions to the input elements. If the mapped * keys contains duplicates (according to {@link Object#equals(Object)}), * the value mapping function is applied to each equal element, and the * results are merged using the provided merging function. The {@code Map} * is created by a provided supplier function. * * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param the type of the resulting {@code Map} * @param keyMapper a mapping function to produce keys * @param valueMapper a mapping function to produce values * @param mergeFunction a merge function, used to resolve collisions between * values associated with the same key, as supplied * to {@link Map#merge(Object, Object, BiFunction)} * @param mapSupplier a function which returns a new, empty {@code Map} into * which the results will be inserted * @return a {@code Collector} which collects elements into a {@code Map} * whose keys are the result of applying a key mapping function to the input * elements, and whose values are the result of applying a value mapping * function to all input elements equal to the key and combining them * using the merge function * * @see #toMap(Function, Function) * @see #toMap(Function, Function, BinaryOperator) * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier) */ public static > Collector toMap(Function keyMapper, Function valueMapper, BinaryOperator mergeFunction, Supplier mapSupplier) { BiFunction accumulator = (map, element) -> { map.merge(keyMapper.apply(element), valueMapper.apply(element), mergeFunction); return map; }; return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_STRICT); } /** * Accumulate elements into a {@code ConcurrentMap} whose keys and values * are the result of applying mapping functions to the input elements. * If the mapped keys contains duplicates (according to * {@link Object#equals(Object)}), an {@code IllegalStateException} is * thrown when the collection operation is performed. If the mapped keys * may have duplicates, use * {@link #toConcurrentMap(Function, Function, BinaryOperator)} instead. * * @apiNote * It is common for either the key or the value to be the input elements. * In this case, the utility method * {@link java.util.function.Function#identity()} may be helpful. * For example, the following produces a {@code Map} mapping * students to their grade point average: *
{@code
     *     Map studentToGPA
     *         students.stream().collect(toMap(Functions.identity(),
     *                                         student -> computeGPA(student)));
     * }
* And the following produces a {@code Map} mapping a unique identifier to * students: *
{@code
     *     Map studentIdToStudent
     *         students.stream().collect(toConcurrentMap(Student::getId,
     *                                                   Functions.identity());
     * }
* *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param keyMapper the mapping function to produce keys * @param valueMapper the mapping function to produce values * @return a concurrent {@code Collector} which collects elements into a * {@code ConcurrentMap} whose keys are the result of applying a key mapping * function to the input elements, and whose values are the result of * applying a value mapping function to the input elements * * @see #toMap(Function, Function) * @see #toConcurrentMap(Function, Function, BinaryOperator) * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier) */ public static Collector> toConcurrentMap(Function keyMapper, Function valueMapper) { return toConcurrentMap(keyMapper, valueMapper, throwingMerger(), ConcurrentHashMap::new); } /** * Accumulate elements into a {@code ConcurrentMap} whose keys and values * are the result of applying mapping functions to the input elements. If * the mapped keys contains duplicates (according to {@link Object#equals(Object)}), * the value mapping function is applied to each equal element, and the * results are merged using the provided merging function. * * @apiNote * There are multiple ways to deal with collisions between multiple elements * mapping to the same key. There are some predefined merging functions, * such as {@link #throwingMerger()}, {@link #firstWinsMerger()}, and * {@link #lastWinsMerger()}, that implement common policies, or you can * implement custom policies easily. For example, if you have a stream * of {@code Person}, and you want to produce a "phone book" mapping name to * address, but it is possible that two persons have the same name, you can * do as follows to gracefully deals with these collisions, and produce a * {@code Map} mapping names to a concatenated list of addresses: *

{@code
     *     Map phoneBook
     *         people.stream().collect(toConcurrentMap(Person::getName,
     *                                                 Person::getAddress,
     *                                                 (s, a) -> s + ", " + a));
     * }
* *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param keyMapper a mapping function to produce keys * @param valueMapper a mapping function to produce values * @param mergeFunction a merge function, used to resolve collisions between * values associated with the same key, as supplied * to {@link Map#merge(Object, Object, BiFunction)} * @return a concurrent {@code Collector} which collects elements into a * {@code ConcurrentMap} whose keys are the result of applying a key mapping * function to the input elements, and whose values are the result of * applying a value mapping function to all input elements equal to the key * and combining them using the merge function * * @see #toConcurrentMap(Function, Function) * @see #toConcurrentMap(Function, Function, BinaryOperator, Supplier) * @see #toMap(Function, Function, BinaryOperator) */ public static Collector> toConcurrentMap(Function keyMapper, Function valueMapper, BinaryOperator mergeFunction) { return toConcurrentMap(keyMapper, valueMapper, mergeFunction, ConcurrentHashMap::new); } /** * Accumulate elements into a {@code ConcurrentMap} whose keys and values * are the result of applying mapping functions to the input elements. If * the mapped keys contains duplicates (according to {@link Object#equals(Object)}), * the value mapping function is applied to each equal element, and the * results are merged using the provided merging function. The * {@code ConcurrentMap} is created by a provided supplier function. * *

This is a {@link Collector.Characteristics#CONCURRENT concurrent} and * {@link Collector.Characteristics#UNORDERED unordered} Collector. * * @param the type of the input elements * @param the output type of the key mapping function * @param the output type of the value mapping function * @param the type of the resulting {@code ConcurrentMap} * @param keyMapper a mapping function to produce keys * @param valueMapper a mapping function to produce values * @param mergeFunction a merge function, used to resolve collisions between * values associated with the same key, as supplied * to {@link Map#merge(Object, Object, BiFunction)} * @param mapSupplier a function which returns a new, empty {@code Map} into * which the results will be inserted * @return a concurrent {@code Collector} which collects elements into a * {@code ConcurrentMap} whose keys are the result of applying a key mapping * function to the input elements, and whose values are the result of * applying a value mapping function to all input elements equal to the key * and combining them using the merge function * * @see #toConcurrentMap(Function, Function) * @see #toConcurrentMap(Function, Function, BinaryOperator) * @see #toMap(Function, Function, BinaryOperator, Supplier) */ public static > Collector toConcurrentMap(Function keyMapper, Function valueMapper, BinaryOperator mergeFunction, Supplier mapSupplier) { BiFunction accumulator = (map, element) -> { map.merge(keyMapper.apply(element), valueMapper.apply(element), mergeFunction); return map; }; return new CollectorImpl<>(mapSupplier, accumulator, mapMerger(mergeFunction), CH_CONCURRENT); } /** * Returns a {@code Collector} which applies an {@code int}-producing * mapping function to each input element, and returns summary statistics * for the resulting values. * * @param the type of the input elements * @param mapper a mapping function to apply to each element * @return a {@code Collector} implementing the summary-statistics reduction * * @see #toDoubleSummaryStatistics(ToDoubleFunction) * @see #toLongSummaryStatistics(ToLongFunction) */ public static Collector toIntSummaryStatistics(ToIntFunction mapper) { return new CollectorImpl<>(IntSummaryStatistics::new, (r, t) -> { r.accept(mapper.applyAsInt(t)); return r; }, (l, r) -> { l.combine(r); return l; }, CH_STRICT); } /** * Returns a {@code Collector} which applies an {@code long}-producing * mapping function to each input element, and returns summary statistics * for the resulting values. * * @param the type of the input elements * @param mapper the mapping function to apply to each element * @return a {@code Collector} implementing the summary-statistics reduction * * @see #toDoubleSummaryStatistics(ToDoubleFunction) * @see #toIntSummaryStatistics(ToIntFunction) */ public static Collector toLongSummaryStatistics(ToLongFunction mapper) { return new CollectorImpl<>(LongSummaryStatistics::new, (r, t) -> { r.accept(mapper.applyAsLong(t)); return r; }, (l, r) -> { l.combine(r); return l; }, CH_STRICT); } /** * Returns a {@code Collector} which applies an {@code double}-producing * mapping function to each input element, and returns summary statistics * for the resulting values. * * @param the type of the input elements * @param mapper a mapping function to apply to each element * @return a {@code Collector} implementing the summary-statistics reduction * * @see #toLongSummaryStatistics(ToLongFunction) * @see #toIntSummaryStatistics(ToIntFunction) */ public static Collector toDoubleSummaryStatistics(ToDoubleFunction mapper) { return new CollectorImpl<>(DoubleSummaryStatistics::new, (r, t) -> { r.accept(mapper.applyAsDouble(t)); return r; }, (l, r) -> { l.combine(r); return l; }, CH_STRICT); } /** * Implementation class used by partitioningBy. */ private static final class Partition extends AbstractMap implements Map { T forTrue; T forFalse; Partition(T forTrue, T forFalse) { this.forTrue = forTrue; this.forFalse = forFalse; } @Override public Set> entrySet() { return new AbstractSet>() { @Override public Iterator> iterator() { return new Iterator>() { int state = 0; @Override public boolean hasNext() { return state < 2; } @Override public Map.Entry next() { if (state >= 2) throw new NoSuchElementException(); return (state++ == 0) ? new SimpleImmutableEntry<>(false, forFalse) : new SimpleImmutableEntry<>(true, forTrue); } }; } @Override public int size() { return 2; } }; } } }