com.github.robtimus.stream

Class AdditionalCollectors

java.lang.Object

com.github.robtimus.stream.AdditionalCollectors

public final class AdditionalCollectors
extends Object

Additional Collector implementations.

Author:

Rob Spoor

Method Summary

Modifier and Type	Method and Description
static <T,A,R> Collector<CompletableFuture<T>,?,CompletableFuture<R>>	completableFutures(Collector<T,A,R> collector) Returns a Collector that accumulates CompletableFuture instances into a new CompletableFuture.
static <T,A,R> Collector<CompletionStage<T>,?,CompletableFuture<R>>	completionStages(Collector<T,A,R> collector) Returns a Collector that accumulates CompletionStage instances into a new CompletableFuture.
static <T> Collector<T,?,Optional<T>>	findSingle() Returns a Collector that finds the single element of a stream, or Optional.empty() if the stream is empty.
static <T> Collector<T,?,Optional<T>>	findSingle(Supplier<? extends RuntimeException> exceptionSupplier) Returns a Collector that finds the single element of a stream, or Optional.empty() if the stream is empty.
static <T> Collector<T,?,Optional<T>>	findUnique() Returns a Collector that finds a unique element of a stream, or Optional.empty() if the stream is empty.
static <T> Collector<T,?,Optional<T>>	findUnique(Supplier<? extends RuntimeException> exceptionSupplier) Returns a Collector that finds the unique element of a stream, or Optional.empty() if the stream is empty.
static <T,A1,R1,A2,R2> Collector<T,?,R2>	partitioning(int partitionSize, Collector<? super T,A1,R1> downstream, Collector<? super R1,A2,R2> partitioner) Returns a Collector that partitions the input elements into portions of a maximum size.
static <T,A,R> Collector<T,A,R>	sequentialOnly(Supplier<A> supplier, BiConsumer<A,T> accumulator, Function<A,R> finisher, Collector.Characteristics... characteristics) Returns a new Collector that only supports sequential streams.
static <T,R> Collector<T,R,R>	sequentialOnly(Supplier<R> supplier, BiConsumer<R,T> accumulator, Collector.Characteristics... characteristics) Returns a new Collector that only supports sequential streams.
static <T,K,V,M extends Map<K,V>> Collector<T,?,M>	toMapWithSupplier(Function<? super T,? extends K> keyMapper, Function<? super T,? extends V> valueMapper, Supplier<M> mapFactory) Returns a Collector that accumulates elements into a Map.

Methods inherited from class java.lang.Object

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

Method Detail

sequentialOnly

public static <T,R> Collector<T,R,R> sequentialOnly(Supplier<R> supplier,
                                                    BiConsumer<R,T> accumulator,
                                                    Collector.Characteristics... characteristics)

Returns a new Collector that only supports sequential streams. If used in a parallel stream, the combine operation will throw an exception.

Type Parameters:

T - The type of input elements for the new Collector.

R - The final result type of the new Collector.

Parameters:

supplier - The supplier function for the new Collector.

accumulator - The accumulator function for the new Collector.

characteristics - The Collector characteristics for the new Collector.

Returns:

The new Collector.

Throws:

NullPointerException - If any argument is null.

See Also:

Collector.of(Supplier, BiConsumer, BinaryOperator, Characteristics...)

sequentialOnly

public static <T,A,R> Collector<T,A,R> sequentialOnly(Supplier<A> supplier,
                                                      BiConsumer<A,T> accumulator,
                                                      Function<A,R> finisher,
                                                      Collector.Characteristics... characteristics)

Returns a new Collector that only supports sequential streams. If used in a parallel stream, the combine operation will throw an exception.

Type Parameters:

T - The type of input elements for the new Collector.

A - The intermediate accumulation type of the new Collector.

R - The final result type of the new Collector.

Parameters:

supplier - The supplier function for the new Collector.

accumulator - The accumulator function for the new Collector.

finisher - The finisher function for the new Collector

characteristics - The Collector characteristics for the new Collector.

Returns:

The new Collector.

Throws:

NullPointerException - If any argument is null.

See Also:

Collector.of(Supplier, BiConsumer, BinaryOperator, Function, Characteristics...)

findSingle

public static <T> Collector<T,?,Optional<T>> findSingle()

Returns a Collector that finds the single element of a stream, or Optional.empty() if the stream is empty.

If the stream contains more than one element, the returned Collector will throw an IllegalStateException. If the stream contains null values, the returned Collector will throw a NullPointerException.

Type Parameters:

T - The type of input element.

Returns:

A Collector that results the single element of a stream

findSingle

public static <T> Collector<T,?,Optional<T>> findSingle(Supplier<? extends RuntimeException> exceptionSupplier)

Returns a Collector that finds the single element of a stream, or Optional.empty() if the stream is empty.

If the stream contains more than one element, the returned Collector will throw an exception provided by the given Supplier. If the stream contains null values, the returned Collector will throw a NullPointerException.

Type Parameters:

T - The type of input element.

Parameters:

exceptionSupplier - A Supplier for the exception to throw if more than one element is encountered.

Returns:

A Collector that results the single element of a stream

findUnique

public static <T> Collector<T,?,Optional<T>> findUnique()

Returns a Collector that finds a unique element of a stream, or Optional.empty() if the stream is empty. Uniqueness is determined using Object.equals(Object).

If the stream contains more than one different element, the returned Collector will throw an IllegalStateException. If the stream contains null values, the returned Collector will throw a NullPointerException.

Type Parameters:

T - The type of input element.

Returns:

A Collector that results the unique element of a stream

findUnique

public static <T> Collector<T,?,Optional<T>> findUnique(Supplier<? extends RuntimeException> exceptionSupplier)

Returns a Collector that finds the unique element of a stream, or Optional.empty() if the stream is empty. Uniqueness is determined using Object.equals(Object).

If the stream contains more than one different element, the returned Collector will throw an exception provided by the given Supplier. If the stream contains null values, the returned Collector will throw a NullPointerException.

Type Parameters:

T - The type of input element.

Parameters:

exceptionSupplier - A Supplier for the exception to throw if more than one element is encountered.

Returns:

A Collector that results the unique element of a stream

toMapWithSupplier

public static <T,K,V,M extends Map<K,V>> Collector<T,?,M> toMapWithSupplier(Function<? super T,? extends K> keyMapper,
                                                                            Function<? super T,? extends V> valueMapper,
                                                                            Supplier<M> mapFactory)

Returns a Collector that accumulates elements into a Map. This method is like Collectors.toMap(Function, Function) but with a custom map factory. It's a convenient alternative to using Collectors.toMap(Function, Function, BinaryOperator, Supplier) without having to write the merge function. Like Collectors.toMap(Function, Function), the value mapping function cannot return null values.

Type Parameters:

T - The type of input element.

K - The output type of the key mapping function.

V - The output type of the value mapping function.

M - The type of resulting Map.

Parameters:

keyMapper - A mapping function to produce map keys.

valueMapper - A mapping function to produce map values.

mapFactory - A supplier providing a new empty Map into which the results will be inserted.

Returns:

A Collector that accumulates elements into a Map.

completionStages

public static <T,A,R> Collector<CompletionStage<T>,?,CompletableFuture<R>> completionStages(Collector<T,A,R> collector)

Returns a Collector that accumulates CompletionStage instances into a new CompletableFuture. If the CompletionStage results need to be mapped or filtered before collecting, use FutureValue instead.

Type Parameters:

T - The result type of the CompletionStage instances.

A - The intermediate accumulation type of the Collector.

R - The result type of the collected CompletableFuture.

Parameters:

collector - The collector for the CompletionStage results.

Returns:

A Collector that collects CompletionStage instances.

Throws:

NullPointerException - If the given Collector is null.

Since:

1.1

completableFutures

public static <T,A,R> Collector<CompletableFuture<T>,?,CompletableFuture<R>> completableFutures(Collector<T,A,R> collector)

Returns a Collector that accumulates CompletableFuture instances into a new CompletableFuture. If the CompletableFuture results need to be mapped or filtered before collecting, use FutureValue instead.

Type Parameters:

T - The result type of the CompletableFuture instances.

A - The intermediate accumulation type of the Collector.

R - The result type of the collected CompletableFuture.

Parameters:

collector - The collector for the CompletableFuture results.

Returns:

A Collector that collects CompletableFuture instances.

Throws:

NullPointerException - If the given Collector is null.

partitioning

public static <T,A1,R1,A2,R2> Collector<T,?,R2> partitioning(int partitionSize,
                                                             Collector<? super T,A1,R1> downstream,
                                                             Collector<? super R1,A2,R2> partitioner)

Returns a Collector that partitions the input elements into portions of a maximum size. Each partition is fed into a downstream Collector, and the results of this downstream Collector are fed into a partitioning Collector.

Note: the returned Collector does not support concurrent streams.

Type Parameters:

T - The type of input elements for the Collector.

A1 - The intermediate accumulation type of the downstream Collector.

R1 - The result type of the downstream Collector.

A2 - The intermediate accumulation type of the partitioning Collector.

R2 - The result type of the partitioning Collector.

Parameters:

partitionSize - The maximum size of each partition.

downstream - The downstream Collector to use. It should not contain any state of its own other than the supplier, accumulator, combiner, finisher and characteristics. Its supplier may be called several times, and each call should yield an "empty" object, and not contain any state from any previous time it is called.

partitioner - The partitioning Collector to use.

Returns:

A Collector that partitions the input elements as described.

Throws:

IllegalArgumentException - If the partition size is not at least 1.

NullPointerException - If either Collector is null.