Skip to content
Buy me a coffee

Collectors

const Collectors: object

Defined in: src/stream/Collectors.ts:606

Ready-made Collectors for stream.collect: into collections and maps, string joining, counting, sums, averages and statistics, min/max and reductions, grouping and partitioning, and adapters (mapping, filtering, flatMapping, collectingAndThen, teeing) that compose into one-pass aggregations. Function arguments that are null throw NullPointerException when the collector first calls them.

averagingDouble: <T>(mapper) => Collector<T, any, number>

Returns a collector of the arithmetic mean of mapper over the elements (compensated summation); 0 when empty.

Compensated summation, as the reference. 0 when no elements.

T

(t) => number

Collector<T, any, number>

averagingInt: <T>(mapper) => Collector<T, any, number>

Returns a collector of the arithmetic mean of mapper over the elements; 0 when empty.

0 when no elements.

T

(t) => number

Collector<T, any, number>

averagingLong: <T>(mapper) => Collector<T, any, number>

Returns a collector of the arithmetic mean of mapper over the elements; 0 when empty.

0 when no elements.

T

(t) => number

Collector<T, any, number>

collectingAndThen: <T, A, R, RR>(downstream, finisher) => Collector<T, A, RR>

Returns a collector that applies finisher to the result of downstream; IDENTITY_FINISH is dropped.

T

A

R

RR

Collector<T, A, R>

(r) => RR

Collector<T, A, RR>

NullPointerException if downstream or finisher is null

counting: <T>() => Collector<T, any, number>

Returns a collector that counts the elements; 0 for an empty stream.

T

Collector<T, any, number>

filtering: <T, A, R>(predicate, downstream) => Collector<T, A, R>

Returns a collector that passes only the elements matching predicate to downstream. As a groupingBy downstream it keeps groups whose elements were all filtered out (with an empty result), unlike a filter before.

T

A

R

(t) => boolean

Collector<T, A, R>

Collector<T, A, R>

flatMapping: <T, U, A, R>(mapper, downstream) => Collector<T, A, R>

Returns a collector that passes every element of the stream mapper returns to downstream. A null/undefined result counts as empty; each mapped stream is closed after its elements are consumed.

Each mapped stream is closed after its elements are consumed; a null/undefined result counts as empty.

T

U

A

R

(t) => ClosableSource<U> | null | undefined

Collector<U, A, R>

Collector<T, A, R>

groupingBy: {<T, K>(classifier): Collector<T, any, Map<K, List<T>>>; <T, K, A, D>(classifier, downstream): Collector<T, any, Map<K, D>>; <T, K, D, A, M>(classifier, mapFactory, downstream): Collector<T, any, M>; }

Returns a collector that groups the elements by classifier into a map from each key to its bucket’s downstream result (default toList(), so each bucket is an ArrayList in encounter order). The default map is a HashMap, whose iteration order is not defined; pass mapFactory (for example () => new TreeMap()) to choose one.

<T, K>(classifier): Collector<T, any, Map<K, List<T>>>

Groups the elements by classifier into a HashMap from each key to a List of the elements with that key, in encounter order.

T

K

(t) => K

Collector<T, any, Map<K, List<T>>>

NullPointerException “element cannot be mapped to a null key” if classifier returns null

<T, K, A, D>(classifier, downstream): Collector<T, any, Map<K, D>>

Groups by classifier into a HashMap, reducing each bucket with downstream.

T

K

A

D

(t) => K

Collector<T, A, D>

Collector<T, any, Map<K, D>>

<T, K, D, A, M>(classifier, mapFactory, downstream): Collector<T, any, M>

Groups by classifier into the map mapFactory() creates, reducing each bucket with downstream.

T

K

D

A

M extends Map<K, D>

(t) => K

() => M

Collector<T, A, D>

Collector<T, any, M>

NullPointerException “element cannot be mapped to a null key” if the classifier returns null

groupingByConcurrent: {<T, K>(classifier): Collector<T, any, Map<K, List<T>>>; <T, K, A, D>(classifier, downstream): Collector<T, any, Map<K, D>>; <T, K, D, A, M>(classifier, mapFactory, downstream): Collector<T, any, M>; }

Returns a collector with the same results as groupingBy, reported as CONCURRENT and UNORDERED. The default map is a HashMap (concurrency is moot on one thread).

<T, K>(classifier): Collector<T, any, Map<K, List<T>>>

Same results as groupingBy (single-threaded runtime), reported as CONCURRENT and UNORDERED. The default map is a HashMap standing in for a concurrent hash map (so null-valued results are not rejected).

T

K

(t) => K

Collector<T, any, Map<K, List<T>>>

<T, K, A, D>(classifier, downstream): Collector<T, any, Map<K, D>>

As groupingBy(classifier, downstream), reported as CONCURRENT and UNORDERED.

T

K

A

D

(t) => K

Collector<T, A, D>

Collector<T, any, Map<K, D>>

<T, K, D, A, M>(classifier, mapFactory, downstream): Collector<T, any, M>

As groupingBy(classifier, mapFactory, downstream), reported as CONCURRENT and UNORDERED.

T

K

D

A

M extends Map<K, D>

(t) => K

() => M

Collector<T, A, D>

Collector<T, any, M>

NullPointerException “element cannot be mapped to a null key” if the classifier returns null

joining: {(): Collector<string | null, any, string>; (delimiter): Collector<string | null, any, string>; (delimiter, prefix, suffix): Collector<string | null, any, string>; }

Returns a collector that concatenates the elements into a string, in encounter order. Optional delimiter between elements, and prefix/suffix around the whole (all three or just the delimiter); an empty stream gives prefix + suffix. A null element is written as "null", other non-strings through their toString.

(): Collector<string | null, any, string>

Concatenates the elements with nothing between them.

Collector<string | null, any, string>

(delimiter): Collector<string | null, any, string>

Concatenates the elements with delimiter between them.

string

Collector<string | null, any, string>

(delimiter, prefix, suffix): Collector<string | null, any, string>

Concatenates the elements with delimiter between them, wrapped in prefix and suffix. A null/undefined argument throws NullPointerException when the collector is used, like the reference.

string

string

string

Collector<string | null, any, string>

NullPointerException (when used) if delimiter, prefix or suffix is null or undefined

mapping: <T, U, A, R>(mapper, downstream) => Collector<T, A, R>

Returns a collector that applies mapper to each element and passes the result to downstream; the result is the downstream’s. Mostly used as a downstream of groupingBy / partitioningBy.

T

U

A

R

(t) => U

Collector<U, A, R>

Collector<T, A, R>

maxBy: <T>(comparator) => Collector<T, any, Optional<NonNullable<T>>>

Returns a collector of the largest element by comparator (the first of equal ones) as an Optional, empty for an empty stream. A null result gives an empty optional.

T

Comparator<T>

Collector<T, any, Optional<NonNullable<T>>>

NullPointerException if comparator is null

minBy: <T>(comparator) => Collector<T, any, Optional<NonNullable<T>>>

Returns a collector of the smallest element by comparator (the first of equal ones) as an Optional, empty for an empty stream. A null result gives an empty optional.

T

Comparator<T>

Collector<T, any, Optional<NonNullable<T>>>

NullPointerException if comparator is null

partitioningBy: {<T>(predicate): Collector<T, any, Map<boolean, List<T>>>; <T, D, A>(predicate, downstream): Collector<T, any, Map<boolean, D>>; }

Returns a collector that splits the elements by predicate into an unmodifiable map with exactly two keys, false then true, both always present; each value is the downstream result (default toList()).

<T>(predicate): Collector<T, any, Map<boolean, List<T>>>

The result always maps both false and true.

T

(t) => boolean

Collector<T, any, Map<boolean, List<T>>>

<T, D, A>(predicate, downstream): Collector<T, any, Map<boolean, D>>

Partitions by predicate, reducing both partitions with downstream.

T

D

A

(t) => boolean

Collector<T, A, D>

Collector<T, any, Map<boolean, D>>

reducing: {<T>(op): Collector<T, any, Optional<NonNullable<T>>>; <T>(identity, op): Collector<T, any, T>; <T, U>(identity, mapper, op): Collector<T, any, U>; }

Returns the collector form of stream.reduce, mostly used as a downstream. reducing(op) gives an Optional (empty when there are no elements or the result is null); reducing(identity, op) gives identity folded with every element; reducing(identity, mapper, op) maps each element first.

<T>(op): Collector<T, any, Optional<NonNullable<T>>>

Reduces with op; an empty Optional when there are no elements (or the result is null).

T

(a, b) => T

Collector<T, any, Optional<NonNullable<T>>>

<T>(identity, op): Collector<T, any, T>

Reduces with op starting from identity; identity when there are no elements.

T

T

(a, b) => T

Collector<T, any, T>

<T, U>(identity, mapper, op): Collector<T, any, U>

Maps each element with mapper, then reduces with op starting from identity.

T

U

U

(t) => U

(a, b) => U

Collector<T, any, U>

summarizingDouble: <T>(mapper) => Collector<T, DoubleSummaryStatistics, DoubleSummaryStatistics>

Returns a collector of a DoubleSummaryStatistics (compensated sums) of mapper over the elements.

T

(t) => number

Collector<T, DoubleSummaryStatistics, DoubleSummaryStatistics>

summarizingInt: <T>(mapper) => Collector<T, IntSummaryStatistics, IntSummaryStatistics>

Returns a collector of an IntSummaryStatistics (count, sum, min, max, average) of mapper over the elements.

T

(t) => number

Collector<T, IntSummaryStatistics, IntSummaryStatistics>

summarizingLong: <T>(mapper) => Collector<T, LongSummaryStatistics, LongSummaryStatistics>

Returns a collector of a LongSummaryStatistics (count, sum, min, max, average) of mapper over the elements.

T

(t) => number

Collector<T, LongSummaryStatistics, LongSummaryStatistics>

summingDouble: <T>(mapper) => Collector<T, any, number>

Returns a collector of the sum of mapper over the elements, using compensated (Kahan) summation; 0 when empty.

Compensated (Kahan) summation, as the reference; an infinite plain sum wins over a NaN compensated one.

T

(t) => number

Collector<T, any, number>

summingInt: <T>(mapper) => Collector<T, any, number>

Returns a collector of the sum of mapper over the elements; 0 when empty. A plain sum: it does not wrap on 32-bit overflow (a difference from the reference).

Plain sum of mapper results; like IntStream.sum() here, int overflow does not wrap (documented difference).

T

(t) => number

Collector<T, any, number>

summingLong: <T>(mapper) => Collector<T, any, number>

Returns a collector of the sum of mapper over the elements; 0 when empty. Exact up to Number.MAX_SAFE_INTEGER.

Plain sum; exact up to Number.MAX_SAFE_INTEGER.

T

(t) => number

Collector<T, any, number>

teeing: <T, R1, R2, R>(downstream1, downstream2, merger) => Collector<T, any, R>

Returns a collector that sends every element to both downstream1 and downstream2 and returns merger(result1, result2): two aggregations in one pass. Its characteristics are those both report, minus IDENTITY_FINISH.

Feeds every element to both downstreams and merges their results. Characteristics: the intersection of both, minus IDENTITY_FINISH.

T

R1

R2

R

Collector<T, any, R1>

Collector<T, any, R2>

(r1, r2) => R

Collector<T, any, R>

NullPointerException if an argument, or a function a downstream returns, is null

toCollection: <T, C>(collectionFactory) => Collector<T, C, C>

Returns a collector that adds the elements, in encounter order, to the collection collectionFactory() creates and returns that collection. Nulls and modifiability are as the collection allows.

T

C extends Collection<T>

() => C

Collector<T, C, C>

toConcurrentMap: {<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>; <T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>; <T, K, U, M>(keyMapper, valueMapper, mergeFunction, mapFactory): Collector<T, any, M>; }

Returns a collector with the same results as toMap, reported as CONCURRENT, UNORDERED and IDENTITY_FINISH. The default map is a HashMap.

<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>

Same results as toMap, reported as CONCURRENT, UNORDERED and IDENTITY_FINISH. Default map: HashMap (null keys are not rejected).

T

K

U

(t) => K

(t) => U

Collector<T, any, Map<K, U>>

<T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>

As toMap(keyMapper, valueMapper, mergeFunction), reported as CONCURRENT, UNORDERED and IDENTITY_FINISH.

T

K

U

(t) => K

(t) => U

(a, b) => U

Collector<T, any, Map<K, U>>

<T, K, U, M>(keyMapper, valueMapper, mergeFunction, mapFactory): Collector<T, any, M>

As toMap(keyMapper, valueMapper, mergeFunction, mapFactory), reported as CONCURRENT, UNORDERED and IDENTITY_FINISH.

T

K

U

M extends Map<K, U>

(t) => K

(t) => U

(a, b) => U

() => M

Collector<T, any, M>

IllegalStateException on a duplicate key without mergeFunction

NullPointerException if a value is null

toList: <T>() => Collector<T, List<T>, List<T>>

Returns a collector into a new, modifiable ArrayList in encounter order; null elements are allowed.

T

Collector<T, List<T>, List<T>>

toMap: {<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>; <T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>; <T, K, U, M>(keyMapper, valueMapper, mergeFunction, mapFactory): Collector<T, any, M>; }

Returns a collector into a map of keyMapper(e) to valueMapper(e), by default a HashMap. Without mergeFunction keys must be unique; with it, values of equal keys are combined as merge(old, new) (a null merge result removes the key). mapFactory chooses the map, for example a LinkedHashMap for encounter order.

<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>

Without mergeFunction: a duplicate key throws IllegalStateException “Duplicate key k (attempted merging values v1 and v2)”; a null value throws NullPointerException. With mergeFunction: values for equal keys are merged (a null value throws NullPointerException, a null merge result removes the key). Default map HashMap.

T

K

U

(t) => K

(t) => U

Collector<T, any, Map<K, U>>

<T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>

Into a HashMap; values of equal keys are combined with mergeFunction(old, new).

T

K

U

(t) => K

(t) => U

(a, b) => U

Collector<T, any, Map<K, U>>

<T, K, U, M>(keyMapper, valueMapper, mergeFunction, mapFactory): Collector<T, any, M>

Into the map mapFactory() creates; values of equal keys are combined with mergeFunction(old, new).

T

K

U

M extends Map<K, U>

(t) => K

(t) => U

(a, b) => U

() => M

Collector<T, any, M>

IllegalStateException “Duplicate key k (attempted merging values v1 and v2)” on a duplicate key without mergeFunction

NullPointerException if a value is null

toSet: <T>() => Collector<T, Set<T>, Set<T>>

Returns a collector into a new, modifiable HashSet (duplicates dropped, no defined order); null is allowed.

T

Collector<T, Set<T>, Set<T>>

toUnmodifiableList: <T>() => Collector<T, List<T>, List<T>>

Returns a collector into an unmodifiable list in encounter order.

T

Collector<T, List<T>, List<T>>

NullPointerException (from the finisher) if an element is null

toUnmodifiableMap: {<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>; <T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>; }

Returns a collector like toMap (same duplicate-key rules) whose result is an unmodifiable map.

<T, K, U>(keyMapper, valueMapper): Collector<T, any, Map<K, U>>

Unmodifiable, null-free result; null keys and values throw NullPointerException, duplicates as toMap.

T

K

U

(t) => K

(t) => U

Collector<T, any, Map<K, U>>

<T, K, U>(keyMapper, valueMapper, mergeFunction): Collector<T, any, Map<K, U>>

As the two-argument form; values of equal keys are combined with mergeFunction(old, new).

T

K

U

(t) => K

(t) => U

(a, b) => U

Collector<T, any, Map<K, U>>

IllegalStateException on a duplicate key without mergeFunction

NullPointerException if a key or value is null, or keyMapper, valueMapper or a given mergeFunction is null

toUnmodifiableSet: <T>() => Collector<T, Set<T>, Set<T>>

Returns a collector into an unmodifiable set; duplicates are dropped.

T

Collector<T, Set<T>, Set<T>>

NullPointerException (from the finisher) if an element is null