java.util.stream

Interface Stream<T>

Type Parameters:

T - Type of elements.

All Known Subinterfaces:

CloseableStream<T>

All Known Implementing Classes:

DelegatingStream

public interface Stream<T>

A sequence of elements supporting sequential and parallel bulk operations. Streams support lazy transformative operations (transforming a stream to another stream) such as filter and map, and consuming operations, such as forEach, findFirst, and iterator. Once an operation has been performed on a stream, it is considered consumed and no longer usable for other operations.

For sequential stream pipelines, all operations are performed respecting in the encounter order of the source, if the source has a defined encounter order. For parallel stream pipelines, unless otherwise specified, intermediate stream operations preserve the encounter order of the source, and terminal operations respect the encounter order of the source, if the source has an encounter order.

Since:

1.8

Method Summary

Modifier and Type	Method and Description
boolean	allMatch(Predicate<? super T> predicate) Return whether all elements of this stream match the provided Predicate.
boolean	anyMatch(Predicate<? super T> predicate) Return whether any elements of this stream match the provided Predicate.
<R> R	collect(Collector<? super T,R> collector) Perform a mutable reduction operation on the elements of this stream using a Collector object to describe the reduction.
<R> R	collect(Supplier<R> resultFactory, BiConsumer<R,? super T> accumulator, BiConsumer<R,R> combiner) Perform a mutable reduction operation on the elements of this stream.
<R> R	collectUnordered(Collector<? super T,R> collector)
Stream<T>	distinct() Transform this stream into one consisting of the distinct elements (according to Object.equals(Object)) of this stream.
Stream<T>	filter(Predicate<? super T> predicate) Transform this stream into one consisting of the elements that match the given Predicate.
Optional<T>	findAny() Return an Optional describing some element of the stream, or an empty Optional if the stream is empty.
Optional<T>	findFirst() Return an Optional describing the first element of this stream, or an empty Optional if the stream is empty.
DoubleStream	flatMap(FlatMapper.ToDouble<? super T> mapper) Transform this stream into a DoubleStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfDouble.
IntStream	flatMap(FlatMapper.ToInt<? super T> mapper) Transform this stream into an IntStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfInt.
LongStream	flatMap(FlatMapper.ToLong<? super T> mapper) Transform this stream into a LongStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfLong.
<R> Stream<R>	flatMap(FlatMapper<? super T,R> mapper) Transform this stream into one where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.
default <R> Stream<R>	flatMap(Function<T,Stream<? extends R>> mapper) Transform this stream into one where each element is replaced with the contents of the stream produced by applying the provided @{code Function} to that element.
void	forEach(Consumer<? super T> consumer) Perform an operation for each element of this stream.
void	forEachUntilCancelled(Consumer<? super T> consumer, BooleanSupplier cancelledFunction) Perform an operation for each element of this stream, attempting to stop early if some external termination condition is reached.
int	getStreamFlags() Return the composition of stream flags of the stream source and all intermediate operations.
boolean	isParallel() Returns whether this stream, when executed, will execute in parallel
default Iterator<T>	iterator() Return an iterator for the elements of this stream.
Stream<T>	limit(long maxSize) Produce a Stream consisting of the elements of this stream, discarding any elements after the maxSize'th elements.
<R> Stream<R>	map(Function<? super T,? extends R> mapper) Transform this stream into one consisting of the result of applying the given Function to the elements of this stream.
DoubleStream	map(ToDoubleFunction<? super T> mapper) Transform this stream into a DoubleStream consisting of the result of applying the given function to the elements of this stream.
IntStream	map(ToIntFunction<? super T> mapper) Transform this stream into an IntStream consisting of the result of applying the given function to the elements of this stream.
LongStream	map(ToLongFunction<? super T> mapper) Transform this stream into a LongStream consisting of the result of applying the given function to the elements of this stream.
default Optional<T>	max(Comparator<? super T> comparator) Return the maximal element of this stream according to the provided Comparator.
default Optional<T>	min(Comparator<? super T> comparator) Return the minimal element of this stream according to the provided Comparator.
boolean	noneMatch(Predicate<? super T> predicate) Return whether no elements of this stream match the provided Predicate.
S	parallel() Produce a stream which has the same contents as this stream, but is a parallel stream.
Stream<T>	peek(Consumer<? super T> consumer) Produce a Stream containing the elements of this stream, and also provide elements to the specified Consumer as elements are consumed from the resulting stream.
Optional<T>	reduce(BinaryOperator<T> reducer) Perform a reduction on the elements of this stream using the provided identity value and an associative reducing function, and return an Optional describing the reduced value, if any.
T	reduce(T identity, BinaryOperator<T> reducer) Perform a reduction on the elements of this stream using the provided identity value and an associative reducing function, and return the reduced value.
<U> U	reduce(U identity, BiFunction<U,? super T,U> reducer, BinaryOperator<U> combiner) Perform a reduction on the elements of this stream, using the provided identity and combining functions.
S	sequential() Produce a stream which has the same contents as this stream, but is a sequential stream.
Stream<T>	sorted() Transform this stream into one consisting of the elements of this stream sorted according to natural order.
Stream<T>	sorted(Comparator<? super T> comparator) Transform this stream into one consisting of the elements of this stream sorted according to the provided Comparator.
Spliterator<T>	spliterator() Return a spliterator for the elements of this stream.
Stream<T>	substream(long startingOffset) Produce a Stream containing the contents of this stream, but discarding the first startingOffset elements.
Stream<T>	substream(long startingOffset, long endingOffset) Produce a Stream that is a subsequence of this stream, discarding the first startingOffset elements of this stream, and discarding any elements after the endingOffset'th element of this stream.
default Object[]	toArray() Produce an array containing the elements of this stream.
<A> A[]	toArray(IntFunction<A[]> generator) Produce an array containing the elements of this stream, using the provided generator function to allocate the returned array.

Method Detail

filter

Stream<T> filter(Predicate<? super T> predicate)

Transform this stream into one consisting of the elements that match the given Predicate. This is an intermediate operation.

Parameters:

predicate - The test criteria to apply to each element to determine if it should be included in the output

map

<R> Stream<R> map(Function<? super T,? extends R> mapper)

Transform this stream into one consisting of the result of applying the given Function to the elements of this stream. This is an intermediate operation.

Parameters:

mapper - The function to be applied to each element

map

IntStream map(ToIntFunction<? super T> mapper)

Transform this stream into an IntStream consisting of the result of applying the given function to the elements of this stream. This is an intermediate operation.

Parameters:

mapper - The function to be applied to each element

map

LongStream map(ToLongFunction<? super T> mapper)

Transform this stream into a LongStream consisting of the result of applying the given function to the elements of this stream. This is an intermediate operation.

Parameters:

mapper - The function to be applied to each element

map

DoubleStream map(ToDoubleFunction<? super T> mapper)

Transform this stream into a DoubleStream consisting of the result of applying the given function to the elements of this stream. This is an intermediate operation.

Parameters:

mapper - The function to be applied to each element

flatMap

default <R> Stream<R> flatMap(Function<T,Stream<? extends R>> mapper)

Transform this stream into one where each element is replaced with the contents of the stream produced by applying the provided @{code Function} to that element. This is an intermediate operation.

Parameters:

mapper - The function to be applied to each element, resulting in a Stream of new values

flatMap

<R> Stream<R> flatMap(FlatMapper<? super T,R> mapper)

Transform this stream into one where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper. This is an intermediate operation.

Parameters:

mapper - The FlatMapper that transforms each element into zero or more resulting values

flatMap

IntStream flatMap(FlatMapper.ToInt<? super T> mapper)

Transform this stream into an IntStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfInt. This is an intermediate operation.

Parameters:

mapper - The FlatMapper that transforms each element into zero or more resulting values

See Also:

#flatMap(FlatMapper)}

flatMap

LongStream flatMap(FlatMapper.ToLong<? super T> mapper)

Transform this stream into a LongStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfLong. This is an intermediate operation.

Parameters:

mapper - The FlatMapper that transforms each element into zero or more resulting values

See Also:

#flatMap(FlatMapper)}

flatMap

DoubleStream flatMap(FlatMapper.ToDouble<? super T> mapper)

Transform this stream into a DoubleStream where each element is replaced with zero or more transformed values, according to the transformation encoded in the provided FlatMapper.OfDouble. This is an intermediate operation.

Parameters:

mapper - The FlatMapper that transforms each element into zero or more resulting values

See Also:

#flatMap(FlatMapper)}

distinct

Stream<T> distinct()

Transform this stream into one consisting of the distinct elements (according to Object.equals(Object)) of this stream. This is a stateful intermediate operation.

sorted

Stream<T> sorted()

Transform this stream into one consisting of the elements of this stream sorted according to natural order. If the elements of this stream are not Comparable, a java.lang.ClassCastException may be thrown when the stream pipeline is executed. This is a stateful intermediate operation.

sorted

Stream<T> sorted(Comparator<? super T> comparator)

Transform this stream into one consisting of the elements of this stream sorted according to the provided Comparator. This is a stateful intermediate operation.

Parameters:

comparator - A Comparator to be used to compare stream elements

forEach

void forEach(Consumer<? super T> consumer)

Perform an operation for each element of this stream. This is a terminal operation.

For parallel stream pipelines, this operation does not guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the operation may be performed at whatever time and in whatever thread the framework chooses. If the operation accesses shared state, it is responsible for providing the required synchronization.

Parameters:

consumer - The Consumer to receive the elements

forEachUntilCancelled

void forEachUntilCancelled(Consumer<? super T> consumer,
                         BooleanSupplier cancelledFunction)

Perform an operation for each element of this stream, attempting to stop early if some external termination condition is reached. This is a short-circuiting terminal operation.

For parallel stream pipelines, this operation does not guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the operation may be performed at whatever time and in whatever thread the framework chooses. If the operation accesses shared state, it is responsible for providing the required synchronization.

Parameters:

consumer - The Consumer to receive the elements

cancelledFunction - A BooleanSupplier that indicates whether the termination criteria has occurred. Once it returns @{code true} the first time, it must continue to return true for all future invocations

peek

Stream<T> peek(Consumer<? super T> consumer)

Produce a Stream containing the elements of this stream, and also provide elements to the specified Consumer as elements are consumed from the resulting stream. This is an intermediate operation. This method exists mainly to support debugging, where you want to see the elements as they flow past a certain point in a pipeline:

     list.stream()
         .filter(filteringFunction)
         .peek(e -> {System.out.println("Filtered value: " + e); });
         .map(mappingFunction)
         .peek(e -> {System.out.println("Mapped value: " + e); });
         .collect(Collectors.intoList());
 

For parallel stream pipelines, the Consumer may be called at whatever time and in whatever thread the element is made available by the upstream operation. If the Consumer modifies shared state, it is responsible for providing the required synchronization.

Parameters:

consumer - The Consumer to receive the elements

limit

Stream<T> limit(long maxSize)

Produce a Stream consisting of the elements of this stream, discarding any elements after the maxSize'th elements. This is a short-circuiting stateful intermediate operation.

Parameters:

maxSize - the number elements the stream should be limited to.

substream

Stream<T> substream(long startingOffset)

Produce a Stream containing the contents of this stream, but discarding the first startingOffset elements. This is a stateful intermediate operation.

Parameters:

startingOffset - the number of elements to be skipped.

substream

Stream<T> substream(long startingOffset,
                  long endingOffset)

Produce a Stream that is a subsequence of this stream, discarding the first startingOffset elements of this stream, and discarding any elements after the endingOffset'th element of this stream. This is a short-circuiting stateful intermediate operation.

Parameters:

startingOffset - the starting position of the substream, inclusive

endingOffset - the ending position of the substream, exclusive

toArray

default Object[] toArray()

Produce an array containing the elements of this stream. This is a terminal operation.

Returns:

an array containing the elements of this stream

toArray

<A> A[] toArray(IntFunction<A[]> generator)

Produce an array containing the elements of this stream, using the provided generator function to allocate the returned array. This is a terminal operation.

Type Parameters:

A - the type of elements in resulting the array

Parameters:

generator - a function which produces a new array of the desired type and the provided length

Returns:

an array containing all of the elements in this stream

Throws:

ArrayStoreException - if the runtime type of an array returned from the array generator is not a supertype of the runtime type of every element in this stream

reduce

T reduce(T identity,
       BinaryOperator<T> reducer)

Perform a reduction on the elements of this stream using the provided identity value and an associative reducing function, and return the reduced value. This is equivalent to:

     T result = identity;
     for (T element : this stream)
         result = reducer.apply(result, element)
     return result;
 

but is not constrained to execute sequentially.

The identity value must be an identity for the reducing function. This means that for all t, reducer(identity, t) is equal to t. The reducer must be an associative function.

This is a terminal operation.

Parameters:

identity - The identity value for the reducing function

reducer - An associative function for combining two elements

Returns:

The result of the reduction

reduce

Optional<T> reduce(BinaryOperator<T> reducer)

Perform a reduction on the elements of this stream using the provided identity value and an associative reducing function, and return an Optional describing the reduced value, if any. This is equivalent to:

     boolean foundAny = false;
     T result = null;
     for (T element : this stream) {
         if (!foundAny) {
             foundAny = true;
             result = element;
         }
         else
             result = reducer.apply(result, element)
     return foundAny ? Optional.of(result) : Optional.empty();
 

but is not constrained to execute sequentially.

The reducer must be an associative function.

This is a terminal operation.

Parameters:

reducer - An associative function for combining two elements

Returns:

The result of the reduction

See Also:

reduce(Object, BinaryOperator)

reduce

<U> U reduce(U identity,
           BiFunction<U,? super T,U> reducer,
           BinaryOperator<U> combiner)

Perform a reduction on the elements of this stream, using the provided identity and combining functions. This is equivalent to:

     U result = identity;
     for (T element : this stream)
         result = reducer.apply(result, element)
     return result;
 

but is not constrained to execute sequentially.

The identity value must be an identity for the combiner function. This means that for all u, combiner(identity, u) is equal to u. Additionally, the combiner function must be compatible with the reducer function; for all u and t, the following must hold:

     combiner(u, reducer(identity, t)) == reducer(u, t)
 

This is a terminal operation.

Type Parameters:

U - The type of the result

Parameters:

identity - The identity value for the combiner function

reducer - An function for combining two results

combiner - A function for incorporating an additional element into a result, which must be compatible with the reducer function

Returns:

The result of the reduction

See Also:

reduce(BinaryOperator), reduce(Object, BinaryOperator)

collect

<R> R collect(Supplier<R> resultFactory,
            BiConsumer<R,? super T> accumulator,
            BiConsumer<R,R> combiner)

Perform a mutable reduction operation on the elements of this stream. A mutable reduction is one in which the reduced value is a mutable value holder, such as an ArrayList, and elements are incorporated by updating the state of the result rather than replacing the result. This is equivalent to:

     R result = resultFactory.get();
     for (T element : this stream)
         accumulator.accept(result, element);
     return result;
 

but is not constrained to execute sequentially.

Type Parameters:

R - Type of the result

Parameters:

resultFactory - Function that creates a new result container. For a parallel execution, this function may be called multiple times and must return a fresh value each time.

accumulator - Function to incorporate a new value into a result container.

combiner - Function to incorporate the state of one result container into another

Returns:

The result of the reduction

collect

<R> R collect(Collector<? super T,R> collector)

Perform a mutable reduction operation on the elements of this stream using a Collector object to describe the reduction. A Collector encapsulates the functions used as arguments to collect(Supplier, BiConsumer, BiConsumer), allowing for reuse of collection strategies and composition of collect operations such as multiple-level group-by.

Type Parameters:

R - The type of the result

Parameters:

collector - The Collector describing the reduction

Returns:

The result of the reduction

See Also:

collect(Supplier, BiConsumer, BiConsumer), Collectors

collectUnordered

<R> R collectUnordered(Collector<? super T,R> collector)

max

default Optional<T> max(Comparator<? super T> comparator)

Return the maximal element of this stream according to the provided Comparator. This is a terminal operation.

Parameters:

comparator - The Comparator to use to compare elements of this stream

Returns:

The maximal element of this stream

min

default Optional<T> min(Comparator<? super T> comparator)

Return the minimal element of this stream according to the provided Comparator. This is a terminal operation.

Parameters:

comparator - The Comparator to use to compare elements of this stream

Returns:

The minimal element of this stream

anyMatch

boolean anyMatch(Predicate<? super T> predicate)

Return whether any elements of this stream match the provided Predicate. May not evaluate the predicate on all elements if not necessary for determining the result. This is a short-circuiting terminal operation.

Parameters:

predicate - The predicate to apply to elements of this stream

Returns:

Whether any elements of the stream match the provided predicate

allMatch

boolean allMatch(Predicate<? super T> predicate)

Return whether all elements of this stream match the provided Predicate. May not evaluate the predicate on all elements if not necessary for determining the result. This is a short-circuiting terminal operation.

Parameters:

predicate - The predicate to apply to elements of this stream

Returns:

Whether all elements of the stream match the provided predicate

noneMatch

boolean noneMatch(Predicate<? super T> predicate)

Return whether no elements of this stream match the provided Predicate. May not evaluate the predicate on all elements if not necessary for determining the result. This is a short-circuiting terminal operation.

Parameters:

predicate - The predicate to apply to elements of this stream

Returns:

Whether no elements of the stream match the provided predicate

findFirst

Optional<T> findFirst()

Return an Optional describing the first element of this stream, or an empty Optional if the stream is empty. This is a short-circuiting terminal operation.

Returns:

The first element of this stream, or an empty Optional if the stream has no elements

findAny

Optional<T> findAny()

Return an Optional describing some element of the stream, or an empty Optional if the stream is empty. This is a short-circuiting terminal operation.

The behavior of this operation is explicitly nondeterministic; it is free to select any element in the stream. This is to allow for maximal performance in parallel operations; the cost is that multiple invocations on the same source may not return the same result. (If the first element in the encounter order is desired, use findFirst() instead.)

Returns:

An element of this stream, or an empty Optional if the stream has no elements

See Also:

findFirst()

iterator

default Iterator<T> iterator()

Return an iterator for the elements of this stream. This is a terminal operation.

Returns:

the element iterator for this stream

spliterator

Spliterator<T> spliterator()

Return a spliterator for the elements of this stream. This is a terminal operation.

Returns:

the element spliterator for this stream

isParallel

boolean isParallel()

Returns whether this stream, when executed, will execute in parallel

Returns:

whether this stream will execute in parallel

getStreamFlags

int getStreamFlags()

Return the composition of stream flags of the stream source and all intermediate operations.

Returns:

the composition of stream flags of the stream source and all intermediate operations

See Also:

StreamOpFlag

sequential

S sequential()

Produce a stream which has the same contents as this stream, but is a sequential stream. If this stream is already sequential, may return itself. This is a stateful intermediate operation.

Returns:

a sequential stream

parallel

S parallel()

Produce a stream which has the same contents as this stream, but is a parallel stream. If this stream is already parallel, may return itself. This is a stateful intermediate operation.

Returns:

a parallel stream