T - the type of the stream elementspublic interfaceStream<T>extendsBaseStream<T,Stream<T>>
Stream andIntStream: int sum = widgets.stream() .filter(w -> w.getColor() == RED) .mapToInt(w -> w.getWeight()) .sum();widgets is aCollection<Widget>. We create a stream ofWidget objects viaCollection.stream(), filter it to produce a stream containing only the red widgets, and then transform it into a stream ofint values representing the weight of each red widget. Then this stream is summed to produce a total weight.In addition toStream, which is a stream of object references, there are primitive specializations forIntStream,LongStream, andDoubleStream, all of which are referred to as "streams" and conform to the characteristics and restrictions described here.
To perform a computation, streamoperations are composed into astream pipeline. A stream pipeline consists of a source (which might be an array, a collection, a generator function, an I/O channel, etc), zero or moreintermediate operations (which transform a stream into another stream, such asfilter(Predicate)), and aterminal operation (which produces a result or side-effect, such ascount() orforEach(Consumer)). Streams are lazy; computation on the source data is only performed when the terminal operation is initiated, and source elements are consumed only as needed.
Collections and streams, while bearing some superficial similarities, have different goals. Collections are primarily concerned with the efficient management of, and access to, their elements. By contrast, streams do not provide a means to directly access or manipulate their elements, and are instead concerned with declaratively describing their source and the computational operations which will be performed in aggregate on that source. However, if the provided stream operations do not offer the desired functionality, theBaseStream.iterator() andBaseStream.spliterator() operations can be used to perform a controlled traversal.
A stream pipeline, like the "widgets" example above, can be viewed as aquery on the stream source. Unless the source was explicitly designed for concurrent modification (such as aConcurrentHashMap), unpredictable or erroneous behavior may result from modifying the stream source while it is being queried.
Most stream operations accept parameters that describe user-specified behavior, such as the lambda expressionw -> w.getWeight() passed tomapToInt in the example above. To preserve correct behavior, thesebehavioral parameters:
Such parameters are always instances of afunctional interface such asFunction, and are often lambda expressions or method references. Unless otherwise specified these parameters must benon-null.
A stream should be operated on (invoking an intermediate or terminal stream operation) only once. This rules out, for example, "forked" streams, where the same source feeds two or more pipelines, or multiple traversals of the same stream. A stream implementation may throwIllegalStateException if it detects that the stream is being reused. However, since some stream operations may return their receiver rather than a new stream object, it may not be possible to detect reuse in all cases.
Streams have aBaseStream.close() method and implementAutoCloseable, but nearly all stream instances do not actually need to be closed after use. Generally, only streams whose source is an IO channel (such as those returned byFiles.lines(Path, Charset)) will require closing. Most streams are backed by collections, arrays, or generating functions, which require no special resource management. (If a stream does require closing, it can be declared as a resource in atry-with-resources statement.)
Stream pipelines may execute either sequentially or inparallel. This execution mode is a property of the stream. Streams are created with an initial choice of sequential or parallel execution. (For example,Collection.stream() creates a sequential stream, andCollection.parallelStream() creates a parallel one.) This choice of execution mode may be modified by theBaseStream.sequential() orBaseStream.parallel() methods, and may be queried with theBaseStream.isParallel() method.
IntStream,LongStream,DoubleStream,java.util.stream| Modifier and Type | Interface | Description |
|---|---|---|
static interface | Stream.Builder<T> | A mutable builder for a Stream. |
| Modifier and Type | Method | Description |
|---|---|---|
boolean | allMatch(Predicate<? superT> predicate) | Returns whether all elements of this stream match the provided predicate. |
boolean | anyMatch(Predicate<? superT> predicate) | Returns whether any elements of this stream match the provided predicate. |
static <T> Stream.Builder<T> | builder() | Returns a builder for a Stream. |
<R,A> R | collect(Collector<? superT,A,R> collector) | Performs amutable reduction operation on the elements of this stream using a Collector. |
<R> R | collect(Supplier<R> supplier,BiConsumer<R,? superT> accumulator,BiConsumer<R,R> combiner) | Performs amutable reduction operation on the elements of this stream. |
static <T> Stream<T> | concat(Stream<? extends T> a,Stream<? extends T> b) | Creates a lazily concatenated stream whose elements are all the elements of the first stream followed by all the elements of the second stream. |
long | count() | Returns the count of elements in this stream. |
Stream<T> | distinct() | Returns a stream consisting of the distinct elements (according to Object.equals(Object)) of this stream. |
static <T> Stream<T> | empty() | Returns an empty sequential Stream. |
Stream<T> | filter(Predicate<? superT> predicate) | Returns a stream consisting of the elements of this stream that match the given predicate. |
Optional<T> | findAny() | Returns an Optional describing some element of the stream, or an emptyOptional if the stream is empty. |
Optional<T> | findFirst() | Returns an Optional describing the first element of this stream, or an emptyOptional if the stream is empty. |
<R> Stream<R> | flatMap(Function<? superT,? extendsStream<? extends R>> mapper) | Returns a stream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. |
DoubleStream | flatMapToDouble(Function<? superT,? extendsDoubleStream> mapper) | Returns an DoubleStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. |
IntStream | flatMapToInt(Function<? superT,? extendsIntStream> mapper) | Returns an IntStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. |
LongStream | flatMapToLong(Function<? superT,? extendsLongStream> mapper) | Returns an LongStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. |
void | forEach(Consumer<? superT> action) | Performs an action for each element of this stream. |
void | forEachOrdered(Consumer<? superT> action) | Performs an action for each element of this stream, in the encounter order of the stream if the stream has a defined encounter order. |
static <T> Stream<T> | generate(Supplier<T> s) | Returns an infinite sequential unordered stream where each element is generated by the provided Supplier. |
static <T> Stream<T> | iterate(T seed,UnaryOperator<T> f) | Returns an infinite sequential ordered Stream produced by iterative application of a functionf to an initial elementseed, producing aStream consisting ofseed,f(seed),f(f(seed)), etc. |
Stream<T> | limit(long maxSize) | Returns a stream consisting of the elements of this stream, truncated to be no longer than maxSize in length. |
<R> Stream<R> | map(Function<? superT,? extends R> mapper) | Returns a stream consisting of the results of applying the given function to the elements of this stream. |
DoubleStream | mapToDouble(ToDoubleFunction<? superT> mapper) | Returns a DoubleStream consisting of the results of applying the given function to the elements of this stream. |
IntStream | mapToInt(ToIntFunction<? superT> mapper) | Returns an IntStream consisting of the results of applying the given function to the elements of this stream. |
LongStream | mapToLong(ToLongFunction<? superT> mapper) | Returns a LongStream consisting of the results of applying the given function to the elements of this stream. |
Optional<T> | max(Comparator<? superT> comparator) | Returns the maximum element of this stream according to the provided Comparator. |
Optional<T> | min(Comparator<? superT> comparator) | Returns the minimum element of this stream according to the provided Comparator. |
boolean | noneMatch(Predicate<? superT> predicate) | Returns whether no elements of this stream match the provided predicate. |
static <T> Stream<T> | of(T... values) | Returns a sequential ordered stream whose elements are the specified values. |
static <T> Stream<T> | of(T t) | Returns a sequential Stream containing a single element. |
Stream<T> | peek(Consumer<? superT> action) | Returns a stream consisting of the elements of this stream, additionally performing the provided action on each element as elements are consumed from the resulting stream. |
Optional<T> | reduce(BinaryOperator<T> accumulator) | Performs areduction on the elements of this stream, using anassociative accumulation function, and returns an Optional describing the reduced value, if any. |
T | reduce(T identity,BinaryOperator<T> accumulator) | Performs areduction on the elements of this stream, using the provided identity value and anassociative accumulation function, and returns the reduced value. |
<U> U | reduce(U identity,BiFunction<U,? superT,U> accumulator,BinaryOperator<U> combiner) | Performs areduction on the elements of this stream, using the provided identity, accumulation and combining functions. |
Stream<T> | skip(long n) | Returns a stream consisting of the remaining elements of this stream after discarding the first n elements of the stream. |
Stream<T> | sorted() | Returns a stream consisting of the elements of this stream, sorted according to natural order. |
Stream<T> | sorted(Comparator<? superT> comparator) | Returns a stream consisting of the elements of this stream, sorted according to the provided Comparator. |
Object[] | toArray() | Returns an array containing the elements of this stream. |
<A> A[] | toArray(IntFunction<A[]> generator) | Returns an array containing the elements of this stream, using the provided generator function to allocate the returned array, as well as any additional arrays that might be required for a partitioned execution or for resizing. |
close,isParallel,iterator,onClose,parallel,sequential,spliterator,unorderedStream<T> filter(Predicate<? superT> predicate)
This is anintermediate operation.
predicate - anon-interfering,stateless predicate to apply to each element to determine if it should be included<R> Stream<R> map(Function<? superT,? extends R> mapper)
This is anintermediate operation.
R - The element type of the new streammapper - anon-interfering,stateless function to apply to each elementIntStream mapToInt(ToIntFunction<? superT> mapper)
IntStream consisting of the results of applying the given function to the elements of this stream.This is an intermediate operation.
mapper - anon-interfering,stateless function to apply to each elementLongStream mapToLong(ToLongFunction<? superT> mapper)
LongStream consisting of the results of applying the given function to the elements of this stream.This is anintermediate operation.
mapper - anon-interfering,stateless function to apply to each elementDoubleStream mapToDouble(ToDoubleFunction<? superT> mapper)
DoubleStream consisting of the results of applying the given function to the elements of this stream.This is anintermediate operation.
mapper - anon-interfering,stateless function to apply to each element<R> Stream<R> flatMap(Function<? superT,? extendsStream<? extends R>> mapper)
closed after its contents have been placed into this stream. (If a mapped stream isnull an empty stream is used, instead.)This is anintermediate operation.
flatMap() operation has the effect of applying a one-to-many transformation to the elements of the stream, and then flattening the resulting elements into a new stream.Examples.
Iforders is a stream of purchase orders, and each purchase order contains a collection of line items, then the following produces a stream containing all the line items in all the orders:
orders.flatMap(order -> order.getLineItems().stream())...Ifpath is the path to a file, then the following produces a stream of thewords contained in that file:
Stream<String> lines = Files.lines(path, StandardCharsets.UTF_8); Stream<String> words = lines.flatMap(line -> Stream.of(line.split(" +")));mapper function passed toflatMap splits a line, using a simple regular expression, into an array of words, and then creates a stream of words from that array.R - The element type of the new streammapper - anon-interfering,stateless function to apply to each element which produces a stream of new valuesIntStream flatMapToInt(Function<? superT,? extendsIntStream> mapper)
IntStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream isclosed after its contents have been placed into this stream. (If a mapped stream isnull an empty stream is used, instead.)This is anintermediate operation.
mapper - anon-interfering,stateless function to apply to each element which produces a stream of new valuesflatMap(Function)LongStream flatMapToLong(Function<? superT,? extendsLongStream> mapper)
LongStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream isclosed after its contents have been placed into this stream. (If a mapped stream isnull an empty stream is used, instead.)This is anintermediate operation.
mapper - anon-interfering,stateless function to apply to each element which produces a stream of new valuesflatMap(Function)DoubleStream flatMapToDouble(Function<? superT,? extendsDoubleStream> mapper)
DoubleStream consisting of the results of replacing each element of this stream with the contents of a mapped stream produced by applying the provided mapping function to each element. Each mapped stream isclosed after its contents have placed been into this stream. (If a mapped stream isnull an empty stream is used, instead.)This is anintermediate operation.
mapper - anon-interfering,stateless function to apply to each element which produces a stream of new valuesflatMap(Function)Stream<T> distinct()
Object.equals(Object)) of this stream.For ordered streams, the selection of distinct elements is stable (for duplicated elements, the element appearing first in the encounter order is preserved.) For unordered streams, no stability guarantees are made.
This is astateful intermediate operation.
distinct() in parallel pipelines is relatively expensive (requires that the operation act as a full barrier, with substantial buffering overhead), and stability is often not needed. Using an unordered stream source (such asgenerate(Supplier)) or removing the ordering constraint withBaseStream.unordered() may result in significantly more efficient execution fordistinct() in parallel pipelines, if the semantics of your situation permit. If consistency with encounter order is required, and you are experiencing poor performance or memory utilization withdistinct() in parallel pipelines, switching to sequential execution withBaseStream.sequential() may improve performance.Stream<T> sorted()
Comparable, ajava.lang.ClassCastException may be thrown when the terminal operation is executed.For ordered streams, the sort is stable. For unordered streams, no stability guarantees are made.
This is astateful intermediate operation.
Stream<T> sorted(Comparator<? superT> comparator)
Comparator.For ordered streams, the sort is stable. For unordered streams, no stability guarantees are made.
This is astateful intermediate operation.
comparator - anon-interfering,statelessComparator to be used to compare stream elementsStream<T> peek(Consumer<? superT> action)
This is anintermediate operation.
For parallel stream pipelines, the action may be called at whatever time and in whatever thread the element is made available by the upstream operation. If the action modifies shared state, it is responsible for providing the required synchronization.
Stream.of("one", "two", "three", "four") .filter(e -> e.length() > 3) .peek(e -> System.out.println("Filtered value: " + e)) .map(String::toUpperCase) .peek(e -> System.out.println("Mapped value: " + e)) .collect(Collectors.toList());action - a non-interfering action to perform on the elements as they are consumed from the streamStream<T> limit(long maxSize)
maxSize in length.limit() is generally a cheap operation on sequential stream pipelines, it can be quite expensive on ordered parallel pipelines, especially for large values ofmaxSize, sincelimit(n) is constrained to return not just anyn elements, but thefirst n elements in the encounter order. Using an unordered stream source (such asgenerate(Supplier)) or removing the ordering constraint withBaseStream.unordered() may result in significant speedups oflimit() in parallel pipelines, if the semantics of your situation permit. If consistency with encounter order is required, and you are experiencing poor performance or memory utilization withlimit() in parallel pipelines, switching to sequential execution withBaseStream.sequential() may improve performance.maxSize - the number of elements the stream should be limited toIllegalArgumentException - ifmaxSize is negativeStream<T> skip(long n)
n elements of the stream. If this stream contains fewer thann elements then an empty stream will be returned.This is astateful intermediate operation.
skip() is generally a cheap operation on sequential stream pipelines, it can be quite expensive on ordered parallel pipelines, especially for large values ofn, sinceskip(n) is constrained to skip not just anyn elements, but thefirst n elements in the encounter order. Using an unordered stream source (such asgenerate(Supplier)) or removing the ordering constraint withBaseStream.unordered() may result in significant speedups ofskip() in parallel pipelines, if the semantics of your situation permit. If consistency with encounter order is required, and you are experiencing poor performance or memory utilization withskip() in parallel pipelines, switching to sequential execution withBaseStream.sequential() may improve performance.n - the number of leading elements to skipIllegalArgumentException - ifn is negativevoid forEach(Consumer<? superT> action)
This is aterminal operation.
The behavior of this operation is explicitly nondeterministic. For parallel stream pipelines, this operation doesnot guarantee to respect the encounter order of the stream, as doing so would sacrifice the benefit of parallelism. For any given element, the action may be performed at whatever time and in whatever thread the library chooses. If the action accesses shared state, it is responsible for providing the required synchronization.
action - a non-interfering action to perform on the elementsvoid forEachOrdered(Consumer<? superT> action)
This is aterminal operation.
This operation processes the elements one at a time, in encounter order if one exists. Performing the action for one elementhappens-before performing the action for subsequent elements, but for any given element, the action may be performed in whatever thread the library chooses.
action - a non-interfering action to perform on the elementsforEach(Consumer)Object[] toArray()
This is aterminal operation.
<A> A[] toArray(IntFunction<A[]> generator)
generator function to allocate the returned array, as well as any additional arrays that might be required for a partitioned execution or for resizing.This is aterminal operation.
Person[] men = people.stream() .filter(p -> p.getGender() == MALE) .toArray(Person[]::new);A - the element type of the resulting arraygenerator - a function which produces a new array of the desired type and the provided lengthArrayStoreException - if the runtime type of the array returned from the array generator is not a supertype of the runtime type of every element in this streamT reduce(T identity,BinaryOperator<T> accumulator)
T result = identity; for (T element : this stream) result = accumulator.apply(result, element) return result;Theidentity value must be an identity for the accumulator function. This means that for allt,accumulator.apply(identity, t) is equal tot. Theaccumulator function must be anassociative function.
This is aterminal operation.
Integer sum = integers.reduce(0, (a, b) -> a+b); Integer sum = integers.reduce(0, Integer::sum);While this may seem a more roundabout way to perform an aggregation compared to simply mutating a running total in a loop, reduction operations parallelize more gracefully, without needing additional synchronization and with greatly reduced risk of data races.
identity - the identity value for the accumulating functionaccumulator - anassociative,non-interfering,stateless function for combining two valuesOptional<T> reduce(BinaryOperator<T> accumulator)
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 = accumulator.apply(result, element); } return foundAny ? Optional.of(result) : Optional.empty();Theaccumulator function must be anassociative function.
This is aterminal operation.
accumulator - anassociative,non-interfering,stateless function for combining two valuesOptional describing the result of the reductionNullPointerException - if the result of the reduction is nullreduce(Object, BinaryOperator),min(Comparator),max(Comparator)<U> U reduce(U identity,BiFunction<U,? superT,U> accumulator,BinaryOperator<U> combiner)
U result = identity; for (T element : this stream) result = accumulator.apply(result, element) return result;Theidentity value must be an identity for the combiner function. This means that for allu,combiner(identity, u) is equal tou. Additionally, thecombiner function must be compatible with theaccumulator function; for allu andt, the following must hold:
combiner.apply(u, accumulator.apply(identity, t)) == accumulator.apply(u, t)This is aterminal operation.
map andreduce operations. Theaccumulator function acts as a fused mapper and accumulator, which can sometimes be more efficient than separate mapping and reduction, such as when knowing the previously reduced value allows you to avoid some computation.U - The type of the resultidentity - the identity value for the combiner functionaccumulator - anassociative,non-interfering,stateless function for incorporating an additional element into a resultcombiner - anassociative,non-interfering,stateless function for combining two values, which must be compatible with the accumulator functionreduce(BinaryOperator),reduce(Object, BinaryOperator)<R> R collect(Supplier<R> supplier,BiConsumer<R,? superT> accumulator,BiConsumer<R,R> combiner)
ArrayList, and elements are incorporated by updating the state of the result rather than by replacing the result. This produces a result equivalent to: R result = supplier.get(); for (T element : this stream) accumulator.accept(result, element); return result;Likereduce(Object, BinaryOperator),collect operations can be parallelized without requiring additional synchronization.
This is aterminal operation.
collect(). For example, the following will accumulate strings into anArrayList: List<String> asList = stringStream.collect(ArrayList::new, ArrayList::add, ArrayList::addAll);The following will take a stream of strings and concatenates them into a single string:
String concat = stringStream.collect(StringBuilder::new, StringBuilder::append, StringBuilder::append) .toString();R - type of the resultsupplier - a 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 - anassociative,non-interfering,stateless function for incorporating an additional element into a resultcombiner - anassociative,non-interfering,stateless function for combining two values, which must be compatible with the accumulator function<R,A> R collect(Collector<? superT,A,R> collector)
Collector. ACollector encapsulates the functions used as arguments tocollect(Supplier, BiConsumer, BiConsumer), allowing for reuse of collection strategies and composition of collect operations such as multiple-level grouping or partitioning.If the stream is parallel, and theCollector isconcurrent, and either the stream is unordered or the collector isunordered, then a concurrent reduction will be performed (seeCollector for details on concurrent reduction.)
This is aterminal operation.
When executed in parallel, multiple intermediate results may be instantiated, populated, and merged so as to maintain isolation of mutable data structures. Therefore, even when executed in parallel with non-thread-safe data structures (such asArrayList), no additional synchronization is needed for a parallel reduction.
List<String> asList = stringStream.collect(Collectors.toList());The following will classifyPerson objects by city:
Map<String, List<Person>> peopleByCity = personStream.collect(Collectors.groupingBy(Person::getCity));The following will classifyPerson objects by state and city, cascading twoCollectors together:
Map<String, Map<String, List<Person>>> peopleByStateAndCity = personStream.collect(Collectors.groupingBy(Person::getState, Collectors.groupingBy(Person::getCity)));R - the type of the resultA - the intermediate accumulation type of theCollectorcollector - theCollector describing the reductioncollect(Supplier, BiConsumer, BiConsumer),CollectorsOptional<T> min(Comparator<? superT> comparator)
Comparator. This is a special case of areduction.This is aterminal operation.
comparator - anon-interfering,statelessComparator to compare elements of this streamOptional describing the minimum element of this stream, or an emptyOptional if the stream is emptyNullPointerException - if the minimum element is nullOptional<T> max(Comparator<? superT> comparator)
Comparator. This is a special case of areduction.This is aterminal operation.
comparator - anon-interfering,statelessComparator to compare elements of this streamOptional describing the maximum element of this stream, or an emptyOptional if the stream is emptyNullPointerException - if the maximum element is nulllong count()
return mapToLong(e -> 1L).sum();This is aterminal operation.
boolean anyMatch(Predicate<? superT> predicate)
false is returned and the predicate is not evaluated.This is ashort-circuiting terminal operation.
predicate - anon-interfering,stateless predicate to apply to elements of this streamtrue if any elements of the stream match the provided predicate, otherwisefalseboolean allMatch(Predicate<? superT> predicate)
true is returned and the predicate is not evaluated.This is ashort-circuiting terminal operation.
true (regardless of P(x)).predicate - anon-interfering,stateless predicate to apply to elements of this streamtrue if either all elements of the stream match the provided predicate or the stream is empty, otherwisefalseboolean noneMatch(Predicate<? superT> predicate)
true is returned and the predicate is not evaluated.This is ashort-circuiting terminal operation.
true, regardless of P(x).predicate - anon-interfering,stateless predicate to apply to elements of this streamtrue if either no elements of the stream match the provided predicate or the stream is empty, otherwisefalseOptional<T> findFirst()
Optional describing the first element of this stream, or an emptyOptional if the stream is empty. If the stream has no encounter order, then any element may be returned.This is ashort-circuiting terminal operation.
Optional describing the first element of this stream, or an emptyOptional if the stream is emptyNullPointerException - if the element selected is nullOptional<T> findAny()
Optional describing some element of the stream, or an emptyOptional if the stream is empty.This is ashort-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 a stable result is desired, usefindFirst() instead.)
Optional describing some element of this stream, or an emptyOptional if the stream is emptyNullPointerException - if the element selected is nullfindFirst()static <T> Stream.Builder<T> builder()
Stream.T - type of elementsstatic <T> Stream<T> empty()
Stream.T - the type of stream elementsstatic <T> Stream<T> of(T t)
Stream containing a single element.T - the type of stream elementst - the single element@SafeVarargsstatic <T> Stream<T> of(T... values)
T - the type of stream elementsvalues - the elements of the new streamstatic <T> Stream<T> iterate(T seed,UnaryOperator<T> f)
Stream produced by iterative application of a functionf to an initial elementseed, producing aStream consisting ofseed,f(seed),f(f(seed)), etc.The first element (position0) in theStream will be the providedseed. Forn > 0, the element at positionn, will be the result of applying the functionf to the element at positionn - 1.
T - the type of stream elementsseed - the initial elementf - a function to be applied to the previous element to produce a new elementStreamstatic <T> Stream<T> generate(Supplier<T> s)
Supplier. This is suitable for generating constant streams, streams of random elements, etc.T - the type of stream elementss - theSupplier of generated elementsStreamstatic <T> Stream<T> concat(Stream<? extends T> a,Stream<? extends T> b)
StackOverflowException.T - The type of stream elementsa - the first streamb - the second stream