java.util.stream

Class Collectors

java.lang.Object

java.util.stream.Collectors

public final class Collectors
extends java.lang.Object

Implementations of 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 Collector implementations in Collectors with the Stream API to perform mutable reduction tasks:

// Accumulate elements into a List
     List list = stream.collect(Collectors.toList());

     // Accumulate elements into a TreeSet
     List list = stream.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(Comparators.comparing(Employee::getSalary)));

     // Group employees by department
     Map<Department, List<Employee>> byDept
         = employees.stream()
                    .collect(Collectors.groupingBy(Employee::getDepartment));

     // Find highest-paid employee by department
     Map<Department, Employee> highestPaidByDept
         = employees.stream()
                    .collect(Collectors.groupingBy(Employee::getDepartment,
                                                   Collectors.maxBy(Comparators.comparing(Employee::getSalary))));

     // Partition students into passing and failing
     Map<Boolean, List<Student>> passingFailing =
         students.stream()
                 .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);

 

TODO explanation of parallel collection

Since:

1.8

Method Summary

Modifier and Type	Method and Description
static <T> Collector<T,java.lang.Long>	counting() Returns a Collector<T, Long> that counts the number of input elements.
static <T> java.util.function.BinaryOperator<T>	firstWinsMerger() Returns a merge function, suitable for use in Map.merge() or toMap(), which implements a "first wins" policy.
static <T,K> Collector<T,java.util.Map<K,java.util.List<T>>>	groupingBy(java.util.function.Function<? super T,? extends K> classifier) Returns a Collector implementing a "group by" operation on input elements of type T, grouping elements according to a classification function.
static <T,K,D> Collector<T,java.util.Map<K,D>>	groupingBy(java.util.function.Function<? super T,? extends K> classifier, Collector<T,D> downstream) Returns a Collector implementing a cascaded "group by" operation on input elements of type 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 Collector.
static <T,K,D,M extends java.util.Map<K,D>> Collector<T,M>	groupingBy(java.util.function.Function<? super T,? extends K> classifier, java.util.function.Supplier<M> mapFactory, Collector<T,D> downstream) Returns a Collector implementing a cascaded "group by" operation on input elements of type 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 Collector.
static <T,K> Collector<T,java.util.concurrent.ConcurrentMap<K,java.util.List<T>>>	groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier) Returns a Collector implementing a concurrent "group by" operation on input elements of type T, grouping elements according to a classification function.
static <T,K,D> Collector<T,java.util.concurrent.ConcurrentMap<K,D>>	groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier, Collector<T,D> downstream) Returns a Collector implementing a concurrent cascaded "group by" operation on input elements of type 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 Collector.
static <T,K,D,M extends java.util.concurrent.ConcurrentMap<K,D>> Collector<T,M>	groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier, java.util.function.Supplier<M> mapFactory, Collector<T,D> downstream) Returns a concurrent Collector implementing a cascaded "group by" operation on input elements of type 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 Collector.
static <T> java.util.function.BinaryOperator<T>	lastWinsMerger() Returns a merge function, suitable for use in Map.merge() or toMap(), which implements a "last wins" policy.
static <T,U,R> Collector<T,R>	mapping(java.util.function.Function<? super T,? extends U> mapper, Collector<U,R> downstream) Adapts a Collector<U,R> to a Collector<T,R> by applying a mapping function to each input element before accumulation.
static <T> Collector<T,T>	maxBy(java.util.Comparator<? super T> comparator) Returns a Collector<T, T> that produces the maximal element according to a given Comparator.
static <T> Collector<T,T>	minBy(java.util.Comparator<? super T> comparator) Returns a Collector<T, T> that produces the minimal element according to a given Comparator.
static <T> Collector<T,java.util.Map<java.lang.Boolean,java.util.List<T>>>	partitioningBy(java.util.function.Predicate<? super T> predicate) Returns a Collector which partitions the input elements according to a Predicate, and organizes them into a Map<Boolean, List<T>>.
static <T,D> Collector<T,java.util.Map<java.lang.Boolean,D>>	partitioningBy(java.util.function.Predicate<? super T> predicate, Collector<T,D> downstream) Returns a Collector which partitions the input elements according to a Predicate, reduces the values in each partition according to another Collector, and organizes them into a Map<Boolean, D> whose values are the result of the downstream reduction.
static <T> Collector<T,T>	reducing(java.util.function.BinaryOperator<T> op) Returns a Collector<T,T> which performs a reduction of its input elements under a specified BinaryOperator.
static <T> Collector<T,T>	reducing(T identity, java.util.function.BinaryOperator<T> op) Returns a Collector<T,T> which performs a reduction of its input elements under a specified BinaryOperator.
static <T,U> Collector<T,U>	reducing(U identity, java.util.function.Function<? super T,? extends U> mapper, java.util.function.BinaryOperator<U> op) Returns a Collector<T,U> which performs a reduction of its input elements under a specified mapping function and BinaryOperator.
static <T> Collector<T,java.lang.Long>	sumBy(java.util.function.Function<? super T,java.lang.Long> mapper) Returns a Collector<T, Long> that produces the sum of a long-valued function applied to the input element.
static <T> java.util.function.BinaryOperator<T>	throwingMerger() Returns a merge function, suitable for use in Map.merge() or toMap(), which always throws IllegalStateException.
static <T,C extends java.util.Collection<T>> Collector<T,C>	toCollection(java.util.function.Supplier<C> collectionFactory) Returns a Collector that accumulates the input elements into a new Collection, in encounter order.
static <T,K,U> Collector<T,java.util.concurrent.ConcurrentMap<K,U>>	toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper) Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements.
static <T,K,U> Collector<T,java.util.concurrent.ConcurrentMap<K,U>>	toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper, java.util.function.BinaryOperator<U> mergeFunction) Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements.
static <T,K,U,M extends java.util.concurrent.ConcurrentMap<K,U>> Collector<T,M>	toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper, java.util.function.BinaryOperator<U> mergeFunction, java.util.function.Supplier<M> mapSupplier) Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements.
static <T> Collector<T,java.util.DoubleSummaryStatistics>	toDoubleSummaryStatistics(java.util.function.ToDoubleFunction<? super T> mapper) Returns a Collector which applies an double-producing mapping function to each input element, and returns summary statistics for the resulting values.
static <T> Collector<T,java.util.IntSummaryStatistics>	toIntSummaryStatistics(java.util.function.ToIntFunction<? super T> mapper) Returns a Collector which applies an int-producing mapping function to each input element, and returns summary statistics for the resulting values.
static <T> Collector<T,java.util.List<T>>	toList() Returns a Collector that accumulates the input elements into a new List.
static <T> Collector<T,java.util.LongSummaryStatistics>	toLongSummaryStatistics(java.util.function.ToLongFunction<? super T> mapper) Returns a Collector which applies an long-producing mapping function to each input element, and returns summary statistics for the resulting values.
static <T,K,U> Collector<T,java.util.Map<K,U>>	toMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper) Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements.
static <T,K,U> Collector<T,java.util.Map<K,U>>	toMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper, java.util.function.BinaryOperator<U> mergeFunction) Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements.
static <T,K,U,M extends java.util.Map<K,U>> Collector<T,M>	toMap(java.util.function.Function<? super T,? extends K> keyMapper, java.util.function.Function<? super T,? extends U> valueMapper, java.util.function.BinaryOperator<U> mergeFunction, java.util.function.Supplier<M> mapSupplier) Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements.
static <T> Collector<T,java.util.Set<T>>	toSet() Returns a Collector that accumulates the input elements into a new Set.
static Collector<java.lang.String,java.lang.StringBuilder>	toStringBuilder() Returns a Collector that concatenates the input elements into a new StringBuilder.
static Collector<java.lang.CharSequence,java.util.StringJoiner>	toStringJoiner(java.lang.String separator) Returns a Collector that concatenates the input elements into a new StringJoiner, using the specified separator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

throwingMerger

public static <T> java.util.function.BinaryOperator<T> throwingMerger()

Returns a merge function, suitable for use in Map.merge() or toMap(), which always throws IllegalStateException. This can be used to enforce the assumption that the elements being collected are distinct.

Type Parameters:

T - The type of input arguments to the merge function

Returns:

A merge function which always throw IllegalStateException

See Also:

firstWinsMerger(), lastWinsMerger()

firstWinsMerger

public static <T> java.util.function.BinaryOperator<T> firstWinsMerger()

Returns a merge function, suitable for use in Map.merge() or toMap(), which implements a "first wins" policy.

Type Parameters:

T - The type of input arguments to the merge function

Returns:

A merge function which always returns its first argument

See Also:

lastWinsMerger(), throwingMerger()

lastWinsMerger

public static <T> java.util.function.BinaryOperator<T> lastWinsMerger()

Returns a merge function, suitable for use in Map.merge() or toMap(), which implements a "last wins" policy.

Type Parameters:

T - The type of input arguments to the merge function

Returns:

A merge function which always returns its second argument

See Also:

firstWinsMerger(), throwingMerger()

toCollection

public static <T,C extends java.util.Collection<T>> Collector<T,C> toCollection(java.util.function.Supplier<C> collectionFactory)

Returns a Collector that accumulates the input elements into a new Collection, in encounter order. The Collection is created by the provided factory.

Type Parameters:

T - The type of the input elements

C - The type of the resulting Collection

Parameters:

collectionFactory - A Supplier which returns a new, empty Collection of the appropriate type

Returns:

A Collector which collects all the input elements into a Collection, in encounter order

toList

public static <T> Collector<T,java.util.List<T>> toList()

Returns a Collector that accumulates the input elements into a new List. There are no guarantees on the type, mutability, serializability, or thread-safety of the List returned.

Type Parameters:

T - The type of the input elements

Returns:

A Collector which collects all the input elements into a List, in encounter order

toSet

public static <T> Collector<T,java.util.Set<T>> toSet()

Returns a Collector that accumulates the input elements into a new Set. There are no guarantees on the type, mutability, serializability, or thread-safety of the Set returned.

Type Parameters:

T - The type of the input elements

Returns:

A Collector which collects all the input elements into a Set

toStringBuilder

public static Collector<java.lang.String,java.lang.StringBuilder> toStringBuilder()

Returns a Collector that concatenates the input elements into a new StringBuilder.

Returns:

A Collector which collects String elements into a StringBuilder, in encounter order

toStringJoiner

public static Collector<java.lang.CharSequence,java.util.StringJoiner> toStringJoiner(java.lang.String separator)

Returns a Collector that concatenates the input elements into a new StringJoiner, using the specified separator.

Parameters:

separator - the separator to be used between each element added to the StringJoiner

Returns:

A Collector which collects String elements into a StringJoiner, in encounter order

mapping

public static <T,U,R> Collector<T,R> mapping(java.util.function.Function<? super T,? extends U> mapper,
                             Collector<U,R> downstream)

Adapts a Collector<U,R> to a Collector<T,R> by applying a mapping function to each input element before accumulation.

Type Parameters:

T - The type of the input elements

U - Type of elements accepted by downstream collector

R - Result type of collector

Parameters:

mapper - A function to be applied to the input elements

downstream - A collector which will accept mapped values

Returns:

A collector which applies the mapping function to the input elements and provides the mapped results to the downstream collector

API Note:

The mapping() collectors are most useful when used in a multi-level reduction, downstream of groupingBy or partitioningBy. For example, given a stream of Person, to accumulate the set of last names in each city:

Map<City, Set<String>> lastNamesByCity
         = people.stream().collect(groupingBy(Person::getCity,
                                              mapping(Person::getLastName, toSet())));
 

counting

public static <T> Collector<T,java.lang.Long> counting()

Returns a Collector<T, Long> that counts the number of input elements.

Type Parameters:

T - The type of the input elements

Returns:

A Collector that counts the input elements

API Note:

This produces a result equivalent to:

reducing(0L, e -> 1L, Long::sum)
 

minBy

public static <T> Collector<T,T> minBy(java.util.Comparator<? super T> comparator)

Returns a Collector<T, T> that produces the minimal element according to a given Comparator.

Type Parameters:

T - The type of the input elements

Parameters:

comparator - A Comparator for comparing elements

Returns:

A Collector that produces the minimal value

API Note:

This produces a result equivalent to:

reducing(Comparators.lesserOf(comparator))
 

maxBy

public static <T> Collector<T,T> maxBy(java.util.Comparator<? super T> comparator)

Returns a Collector<T, T> that produces the maximal element according to a given Comparator.

Type Parameters:

T - The type of the input elements

Parameters:

comparator - A Comparator for comparing elements

Returns:

A Collector that produces the maximal value

API Note:

This produces a result equivalent to:

reducing(Comparators.greaterOf(comparator))
 

sumBy

public static <T> Collector<T,java.lang.Long> sumBy(java.util.function.Function<? super T,java.lang.Long> mapper)

Returns a Collector<T, Long> that produces the sum of a long-valued function applied to the input element.

Type Parameters:

T - The type of the input elements

Parameters:

mapper - A function extracting the property to be summed

Returns:

A Collector that produces the sum of a derived property

API Note:

This produces a result equivalent to:

reducing(0L, mapper, Long::sum)
 

reducing

public static <T> Collector<T,T> reducing(T identity,
                          java.util.function.BinaryOperator<T> op)

Returns a Collector<T,T> which performs a reduction of its input elements under a specified BinaryOperator.

Type Parameters:

T - Element type for the input and output of the reduction

Parameters:

identity - The identity value for the reduction (also, the value that is returned when there are no input elements)

op - A BinaryOperator<T> used to reduce the input elements

Returns:

A Collector which implements the reduction operation

See Also:

reducing(BinaryOperator), reducing(Object, Function, BinaryOperator)

API Note:

The reducing() collectors are most useful when used in a multi-level reduction, downstream of groupingBy or partitioningBy. To perform a simple reduction on a stream, use Stream.reduce(BinaryOperator) instead.

reducing

public static <T> Collector<T,T> reducing(java.util.function.BinaryOperator<T> op)

Returns a Collector<T,T> which performs a reduction of its input elements under a specified BinaryOperator.

Type Parameters:

T - Element type for the input and output of the reduction

Parameters:

op - A BinaryOperator<T> used to reduce the input elements

Returns:

A Collector which implements the reduction operation

See Also:

reducing(Object, BinaryOperator), reducing(Object, Function, BinaryOperator)

API Note:

The reducing() collectors are most useful when used in a multi-level reduction, downstream of groupingBy or partitioningBy. To perform a simple reduction on a stream, use Stream.reduce(BinaryOperator) instead.

For example, given a stream of Person, to calculate tallest person in each city:

Comparator<Person> byHeight = Comparators.comparing(Person::getHeight);
     BinaryOperator<Person> tallerOf = Comparators.greaterOf(byHeight);
     Map<City, Person> tallestByCity
         = people.stream().collect(groupingBy(Person::getCity, reducing(tallerOf)));
 

reducing

public static <T,U> Collector<T,U> reducing(U identity,
                            java.util.function.Function<? super T,? extends U> mapper,
                            java.util.function.BinaryOperator<U> op)

Returns a Collector<T,U> which performs a reduction of its input elements under a specified mapping function and BinaryOperator. This is a generalization of reducing(Object, BinaryOperator) which allows a transformation of the elements before reduction.

Type Parameters:

T - The type of the input elements

U - The type of the mapped values

Parameters:

identity - The identity value for the reduction (also, the value that is returned when there are no input elements)

mapper - A mapping function to apply to each input value

op - A BinaryOperator<U> used to reduce the mapped values

Returns:

A Collector implementing the map-reduce operation

See Also:

reducing(Object, BinaryOperator), reducing(BinaryOperator)

API Note:

The reducing() collectors are most useful when used in a multi-level reduction, downstream of groupingBy or partitioningBy. To perform a simple reduction on a stream, use Stream.reduce(BinaryOperator) instead.

For example, given a stream of Person, to calculate the longest last name of residents in each city:

Comparator<String> byLength = Comparators.comparing(String::length);
     BinaryOperator<String> longerOf = Comparators.greaterOf(byLength);
     Map<City, String> longestLastNameByCity
         = people.stream().collect(groupingBy(Person::getCity,
                                              reducing(Person::getLastName, longerOf)));
 

groupingBy

public static <T,K> Collector<T,java.util.Map<K,java.util.List<T>>> groupingBy(java.util.function.Function<? super T,? extends K> classifier)

Returns a Collector implementing a "group by" operation on input elements of type T, grouping elements according to a classification function.

The classification function maps elements to some key type K. The collector produces a Map<K, List<T>> whose keys are the values resulting from applying the classification function to the input elements, and whose corresponding values are Lists 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 Map or List objects returned.

Type Parameters:

T - The type of the input elements

K - The type of the keys

Parameters:

classifier - The classifier function mapping input elements to keys

Returns:

A Collector implementing the group-by operation

See Also:

groupingBy(Function, Collector), groupingBy(Function, Supplier, Collector), groupingByConcurrent(Function)

API Note:

This produces a result similar to:

groupingBy(classifier, toList());
 

groupingBy

public static <T,K,D> Collector<T,java.util.Map<K,D>> groupingBy(java.util.function.Function<? super T,? extends K> classifier,
                                                 Collector<T,D> downstream)

Returns a Collector implementing a cascaded "group by" operation on input elements of type 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 Collector.

The classification function maps elements to some key type K. The downstream collector operates on elements of type T and produces a result of type D. The resulting collector produces a Map<K, D>.

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

Map<City, Set<String>> namesByCity
         = people.stream().collect(groupingBy(Person::getCity,
                                              mapping(Person::getLastName, toSet())));
 

There are no guarantees on the type, mutability, serializability, or thread-safety of the Map returned.

Type Parameters:

T - The type of the input elements

K - The type of the keys

D - The result type of the downstream reduction

Parameters:

classifier - The classifier function mapping input elements to keys

downstream - A Collector implementing the downstream reduction

Returns:

A Collector implementing the cascaded group-by operation

See Also:

groupingBy(Function), groupingBy(Function, Supplier, Collector), groupingByConcurrent(Function, Collector)

groupingBy

public static <T,K,D,M extends java.util.Map<K,D>> Collector<T,M> groupingBy(java.util.function.Function<? super T,? extends K> classifier,
                                                             java.util.function.Supplier<M> mapFactory,
                                                             Collector<T,D> downstream)

Returns a Collector implementing a cascaded "group by" operation on input elements of type 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 Collector. The Map produced by the Collector is created with the supplied factory function.

The classification function maps elements to some key type K. The downstream collector operates on elements of type T and produces a result of type D. The resulting collector produces a Map<K, D>.

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

Map<City, Set<String>> namesByCity
         = people.stream().collect(groupingBy(Person::getCity, TreeMap::new,
                                              mapping(Person::getLastName, toSet())));
 

Type Parameters:

T - The type of the input elements

K - The type of the keys

D - The result type of the downstream reduction

M - The type of the resulting Map

Parameters:

classifier - The classifier function mapping input elements to keys

downstream - A Collector implementing the downstream reduction

mapFactory - A function which, when called, produces a new empty Map of the desired type

Returns:

A Collector implementing the cascaded group-by operation

See Also:

groupingBy(Function, Collector), groupingBy(Function), groupingByConcurrent(Function, Supplier, Collector)

groupingByConcurrent

public static <T,K> Collector<T,java.util.concurrent.ConcurrentMap<K,java.util.List<T>>> groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier)

Returns a Collector implementing a concurrent "group by" operation on input elements of type T, grouping elements according to a classification function.

This is a concurrent and unordered Collector.

The classification function maps elements to some key type K. The collector produces a ConcurrentMap<K, List<T>> whose keys are the values resulting from applying the classification function to the input elements, and whose corresponding values are Lists 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 Map or List objects returned.

Type Parameters:

T - The type of the input elements

K - The type of the keys

Parameters:

classifier - The classifier function mapping input elements to keys

Returns:

A Collector implementing the group-by operation

See Also:

groupingBy(Function), groupingByConcurrent(Function, Collector), groupingByConcurrent(Function, Supplier, Collector)

API Note:

This produces a result similar to:

groupingByConcurrent(classifier, toList());
 

groupingByConcurrent

public static <T,K,D> Collector<T,java.util.concurrent.ConcurrentMap<K,D>> groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier,
                                                                                Collector<T,D> downstream)

Returns a Collector implementing a concurrent cascaded "group by" operation on input elements of type 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 Collector.

This is a concurrent and unordered Collector.

The classification function maps elements to some key type K. The downstream collector operates on elements of type T and produces a result of type D. The resulting collector produces a Map<K, D>.

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

ConcurrentMap<City, Set<String>> namesByCity
         = people.stream().collect(groupingByConcurrent(Person::getCity, TreeMap::new,
                                                        mapping(Person::getLastName, toSet())));
 

Type Parameters:

T - The type of the input elements

K - The type of the keys

D - The result type of the downstream reduction

Parameters:

classifier - The classifier function mapping input elements to keys

downstream - A Collector implementing the downstream reduction

Returns:

A Collector implementing the cascaded group-by operation

See Also:

groupingBy(Function, Collector), groupingByConcurrent(Function), groupingByConcurrent(Function, Supplier, Collector)

groupingByConcurrent

public static <T,K,D,M extends java.util.concurrent.ConcurrentMap<K,D>> Collector<T,M> groupingByConcurrent(java.util.function.Function<? super T,? extends K> classifier,
                                                                                            java.util.function.Supplier<M> mapFactory,
                                                                                            Collector<T,D> downstream)

Returns a concurrent Collector implementing a cascaded "group by" operation on input elements of type 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 Collector. The ConcurrentMap produced by the Collector is created with the supplied factory function.

This is a concurrent and unordered Collector.

The classification function maps elements to some key type K. The downstream collector operates on elements of type T and produces a result of type D. The resulting collector produces a Map<K, D>.

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

ConcurrentMap<City, Set<String>> namesByCity
         = people.stream().collect(groupingBy(Person::getCity, ConcurrentSkipListMap::new,
                                              mapping(Person::getLastName, toSet())));
 

Type Parameters:

T - The type of the input elements

K - The type of the keys

D - The result type of the downstream reduction

M - The type of the resulting ConcurrentMap

Parameters:

classifier - The classifier function mapping input elements to keys

downstream - A Collector implementing the downstream reduction

mapFactory - A function which, when called, produces a new empty ConcurrentMap of the desired type

Returns:

A Collector implementing the cascaded group-by operation

See Also:

groupingByConcurrent(Function), groupingByConcurrent(Function, Collector), groupingBy(Function, Supplier, Collector)

partitioningBy

public static <T> Collector<T,java.util.Map<java.lang.Boolean,java.util.List<T>>> partitioningBy(java.util.function.Predicate<? super T> predicate)

Returns a Collector which partitions the input elements according to a Predicate, and organizes them into a Map<Boolean, List<T>>. There are no guarantees on the type, mutability, serializability, or thread-safety of the Map returned.

Type Parameters:

T - The type of the input elements

Parameters:

predicate - The predicate used for classifying input elements

Returns:

A Collector implementing the partitioning operation.

See Also:

partitioningBy(Predicate, Collector)

partitioningBy

public static <T,D> Collector<T,java.util.Map<java.lang.Boolean,D>> partitioningBy(java.util.function.Predicate<? super T> predicate,
                                                                   Collector<T,D> downstream)

Returns a Collector which partitions the input elements according to a Predicate, reduces the values in each partition according to another Collector, and organizes them into a Map<Boolean, D> whose values are the result of the downstream reduction. There are no guarantees on the type, mutability, serializability, or thread-safety of the Map returned.

Type Parameters:

T - The type of the input elements

D - The result type of the downstream reduction

Parameters:

predicate - The predicate used for classifying input elements

downstream - A Collector implementing the downstream reduction

Returns:

A Collector implementing the cascaded partitioning operation.

See Also:

partitioningBy(Predicate)

toMap

public static <T,K,U> Collector<T,java.util.Map<K,U>> toMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                            java.util.function.Function<? super T,? extends U> valueMapper)

Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), an IllegalStateException is thrown when the collection operation is performed. If the mapped keys may have duplicates, use toMap(Function, Function, BinaryOperator) instead.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

Returns:

A Collector which collects elements into a Map whose keys and values are the result of applying mapping functions to the input elements

See Also:

toMap(Function, Function, BinaryOperator), toMap(Function, Function, BinaryOperator, Supplier), toConcurrentMap(Function, Function)

API Note:

It is common for either the key or the value to be the input elements. In this case, the utility method Functions.identity() may be helpful. For example, the following produces a Map mapping students to their grade point average:

Map<Student, Double> studentToGPA
         students.stream().collect(toMap(Functions.identity(),
                                         student -> computeGPA(student)));
 

And the following produces a Map mapping a unique identifier to students:

Map<String, Student> studentIdToStudent
         students.stream().collect(toMap(Student::getId,
                                         Functions.identity());
 

toMap

public static <T,K,U> Collector<T,java.util.Map<K,U>> toMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                            java.util.function.Function<? super T,? extends U> valueMapper,
                                            java.util.function.BinaryOperator<U> mergeFunction)

Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), the value mapping function is applied to each equal element, and the results are merged using the provided merging function.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

mergeFunction - A merge function, used to resolve collisions between values associated with the same key, as supplied to Map.merge(Object, Object, BiFunction)

Returns:

A Collector which collects elements into a 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 Also:

toMap(Function, Function), toMap(Function, Function, BinaryOperator, Supplier), toConcurrentMap(Function, Function, BinaryOperator)

API Note:

There are multiple ways to deal with collisions between multiple elements mapping to the same key. There are some predefined merging functions, such as throwingMerger(), firstWinsMerger(), and lastWinsMerger(), that implement common policies, or you can implement custom policies easily. For example, if you have a stream of 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 Map mapping names to a concatened list of addresses:

Map<String, String> phoneBook
         people.stream().collect(toMap(Person::getName,
                                       Person::getAddress,
                                       (s, a) -> s + ", " + a));
 

toMap

public static <T,K,U,M extends java.util.Map<K,U>> Collector<T,M> toMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                                        java.util.function.Function<? super T,? extends U> valueMapper,
                                                        java.util.function.BinaryOperator<U> mergeFunction,
                                                        java.util.function.Supplier<M> mapSupplier)

Accumulate elements into a Map whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), the value mapping function is applied to each equal element, and the results are merged using the provided merging function. The Map is created by a provided supplier function.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

M - The type of the resulting Map

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

mergeFunction - A merge function, used to resolve collisions between values associated with the same key, as supplied to Map.merge(Object, Object, BiFunction)

mapSupplier - A function which returns a new, empty Map into which the results will be inserted

Returns:

A Collector which collects elements into a 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 Also:

toMap(Function, Function), toMap(Function, Function, BinaryOperator), toConcurrentMap(Function, Function, BinaryOperator, Supplier)

toConcurrentMap

public static <T,K,U> Collector<T,java.util.concurrent.ConcurrentMap<K,U>> toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                                                           java.util.function.Function<? super T,? extends U> valueMapper)

Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), an IllegalStateException is thrown when the collection operation is performed. If the mapped keys may have duplicates, use toConcurrentMap(Function, Function, BinaryOperator) instead.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

Returns:

A concurrent Collector which collects elements into a 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 Also:

toMap(Function, Function), toConcurrentMap(Function, Function, BinaryOperator), toConcurrentMap(Function, Function, BinaryOperator, Supplier)

API Note:

It is common for either the key or the value to be the input elements. In this case, the utility method Functions.identity() may be helpful. For example, the following produces a Map mapping students to their grade point average:

Map<Student, Double> studentToGPA
         students.stream().collect(toMap(Functions.identity(),
                                         student -> computeGPA(student)));
 

And the following produces a Map mapping a unique identifier to students:

Map<String, Student> studentIdToStudent
         students.stream().collect(toConcurrentMap(Student::getId,
                                                   Functions.identity());
 

This is a concurrent and unordered Collector.

toConcurrentMap

public static <T,K,U> Collector<T,java.util.concurrent.ConcurrentMap<K,U>> toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                                                           java.util.function.Function<? super T,? extends U> valueMapper,
                                                                           java.util.function.BinaryOperator<U> mergeFunction)

Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), the value mapping function is applied to each equal element, and the results are merged using the provided merging function.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

mergeFunction - A merge function, used to resolve collisions between values associated with the same key, as supplied to Map.merge(Object, Object, BiFunction)

Returns:

A concurrent Collector which collects elements into a 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 Also:

toConcurrentMap(Function, Function), toConcurrentMap(Function, Function, BinaryOperator, Supplier), toMap(Function, Function, BinaryOperator)

API Note:

There are multiple ways to deal with collisions between multiple elements mapping to the same key. There are some predefined merging functions, such as throwingMerger(), firstWinsMerger(), and lastWinsMerger(), that implement common policies, or you can implement custom policies easily. For example, if you have a stream of 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 Map mapping names to a concatened list of addresses:

Map<String, String> phoneBook
         people.stream().collect(toConcurrentMap(Person::getName,
                                                 Person::getAddress,
                                                 (s, a) -> s + ", " + a));
 

This is a concurrent and unordered Collector.

toConcurrentMap

public static <T,K,U,M extends java.util.concurrent.ConcurrentMap<K,U>> Collector<T,M> toConcurrentMap(java.util.function.Function<? super T,? extends K> keyMapper,
                                                                                       java.util.function.Function<? super T,? extends U> valueMapper,
                                                                                       java.util.function.BinaryOperator<U> mergeFunction,
                                                                                       java.util.function.Supplier<M> mapSupplier)

Accumulate elements into a ConcurrentMap whose keys and values are the result of applying mapping functions to the input elements. If the mapped keys contains duplicates (according to Object.equals(Object)), the value mapping function is applied to each equal element, and the results are merged using the provided merging function. The ConcurrentMap is created by a provided supplier function.

This is a concurrent and unordered Collector.

Type Parameters:

T - The type of the input elements

K - The output type of the key mapping function

U - The output type of the value mapping function

M - The type of the resulting ConcurrentMap

Parameters:

keyMapper - The mapping function to produce keys

valueMapper - The mapping function to produce values

mergeFunction - A merge function, used to resolve collisions between values associated with the same key, as supplied to Map.merge(Object, Object, BiFunction)

mapSupplier - A function which returns a new, empty Map into which the results will be inserted

Returns:

A concurrent Collector which collects elements into a 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 Also:

toConcurrentMap(Function, Function), toConcurrentMap(Function, Function, BinaryOperator), toMap(Function, Function, BinaryOperator, Supplier)

toIntSummaryStatistics

public static <T> Collector<T,java.util.IntSummaryStatistics> toIntSummaryStatistics(java.util.function.ToIntFunction<? super T> mapper)

Returns a Collector which applies an int-producing mapping function to each input element, and returns summary statistics for the resulting values.

Type Parameters:

T - The type of the input elements

Parameters:

mapper - The mapping function to apply to each element

Returns:

A Collector implementing the summary-statistics reduction

See Also:

toDoubleSummaryStatistics(ToDoubleFunction), toLongSummaryStatistics(ToLongFunction)

toLongSummaryStatistics

public static <T> Collector<T,java.util.LongSummaryStatistics> toLongSummaryStatistics(java.util.function.ToLongFunction<? super T> mapper)

Returns a Collector which applies an long-producing mapping function to each input element, and returns summary statistics for the resulting values.

Type Parameters:

T - The type of the input elements

Parameters:

mapper - The mapping function to apply to each element

Returns:

A Collector implementing the summary-statistics reduction

See Also:

toDoubleSummaryStatistics(ToDoubleFunction), toIntSummaryStatistics(ToIntFunction)

toDoubleSummaryStatistics

public static <T> Collector<T,java.util.DoubleSummaryStatistics> toDoubleSummaryStatistics(java.util.function.ToDoubleFunction<? super T> mapper)

Returns a Collector which applies an double-producing mapping function to each input element, and returns summary statistics for the resulting values.

Type Parameters:

T - The type of the input elements

Parameters:

mapper - The mapping function to apply to each element

Returns:

A Collector implementing the summary-statistics reduction

See Also:

toLongSummaryStatistics(ToLongFunction), toIntSummaryStatistics(ToIntFunction)