int sum = widgets.stream()
                 .filter(w -> w.getColor() == RED)
                 .mapToInt(w -> w.getWeight())
                 .sum();

Base interface for streams, which are sequences of elements supporting
sequential and parallel aggregate operations.  The following example
illustrates an aggregate operation using the stream types Stream
and IntStream, computing the sum of the weights of the red widgets:



    int sum = widgets.stream()
                     .filter(w -> w.getColor() == RED)
                     .mapToInt(w -> w.getWeight())
                     .sum();

See the class documentation for Stream and the package documentation
for java.util.stream for additional
specification of streams, stream operations, stream pipelines, and
parallelism, which governs the behavior of all stream types.

A a1 = supplier.get();
accumulator.accept(a1, t1);
accumulator.accept(a1, t2);
R r1 = finisher.apply(a1);  // result without splitting

A a2 = supplier.get();
accumulator.accept(a2, t1);
A a3 = supplier.get();
accumulator.accept(a3, t2);
R r2 = finisher.apply(combiner.apply(a2, a3));  // result with splitting

The first argument passed to the accumulator function, both
arguments passed to the combiner function, and the argument passed to the
finisher function must be the result of a previous invocation of the
result supplier, accumulator, or combiner functions.
The implementation should not do anything with the result of any of
the result supplier, accumulator, or combiner functions other than to
pass them again to the accumulator, combiner, or finisher functions,
or return them to the caller of the reduction operation.
If a result is passed to the combiner or finisher
function, and the same object is not returned from that function, it is
never used again.
Once a result is passed to the combiner or finisher function, it
is never passed to the accumulator function again.
For non-concurrent collectors, any result returned from the result
supplier, accumulator, or combiner functions must be serially
thread-confined.  This enables collection to occur in parallel without
the Collector needing to implement any additional synchronization.
The reduction implementation must manage that the input is properly
partitioned, that partitions are processed in isolation, and combining
happens only after accumulation is complete.
For concurrent collectors, an implementation is free to (but not
required to) implement reduction concurrently.  A concurrent reduction
is one where the accumulator function is called concurrently from
multiple threads, using the same concurrently-modifiable result container,
rather than keeping the result isolated during accumulation.
A concurrent reduction should only be applied if the collector has the
Collector.Characteristics.UNORDERED characteristics or if the
originating data is unordered.

Collector<Widget, ?, TreeSet<Widget>> intoSet =
    Collector.of(TreeSet::new, TreeSet::add,
                 (left, right) -> { left.addAll(right); return left; });

A mutable reduction operation that
accumulates input elements into a mutable result container, optionally transforming
the accumulated result into a final representation after all input elements
have been processed.  Reduction operations can be performed either sequentially
or in parallel.

Examples of mutable reduction operations include:
accumulating elements into a Collection; concatenating
strings using a StringBuilder; computing summary information about
elements such as sum, min, max, or average; computing "pivot table" summaries
such as "maximum valued transaction by seller", etc.  The class Collectors
provides implementations of many common mutable reductions.

A Collector is specified by four functions that work together to
accumulate entries into a mutable result container, and optionally perform
a final transform on the result.  They are:
    creation of a new result container (supplier())
    incorporating a new data element into a result container (accumulator())
    combining two result containers into one (combiner())
    performing an optional final transform on the container (finisher())


Collectors also have a set of characteristics, such as
Collector.Characteristics.CONCURRENT, that provide hints that can be used by a
reduction implementation to provide better performance.

A sequential implementation of a reduction using a collector would
create a single result container using the supplier function, and invoke the
accumulator function once for each input element.  A parallel implementation
would partition the input, create a result container for each partition,
accumulate the contents of each partition into a subresult for that partition,
and then use the combiner function to merge the subresults into a combined
result.

To ensure that sequential and parallel executions produce equivalent
results, the collector functions must satisfy an identity and an
associativity constraints.

The identity constraint says that for any partially accumulated result,
combining it with an empty result container must produce an equivalent
result.  That is, for a partially accumulated result a that is the
result of any series of accumulator and combiner invocations, a must
be equivalent to combiner.apply(a, supplier.get()).

The associativity constraint says that splitting the computation must
produce an equivalent result.  That is, for any input elements t1
and t2, the results r1 and r2 in the computation
below must be equivalent:


    A a1 = supplier.get();
    accumulator.accept(a1, t1);
    accumulator.accept(a1, t2);
    R r1 = finisher.apply(a1);  // result without splitting

    A a2 = supplier.get();
    accumulator.accept(a2, t1);
    A a3 = supplier.get();
    accumulator.accept(a3, t2);
    R r2 = finisher.apply(combiner.apply(a2, a3));  // result with splitting

For collectors that do not have the UNORDERED characteristic,
two accumulated results a1 and a2 are equivalent if
finisher.apply(a1).equals(finisher.apply(a2)).  For unordered
collectors, equivalence is relaxed to allow for non-equality related to
differences in order.  (For example, an unordered collector that accumulated
elements to a List would consider two lists equivalent if they
contained the same elements, ignoring order.)

Libraries that implement reduction based on Collector, such as
Stream.collect(Collector), must adhere to the following constraints:

    The first argument passed to the accumulator function, both
    arguments passed to the combiner function, and the argument passed to the
    finisher function must be the result of a previous invocation of the
    result supplier, accumulator, or combiner functions.
    The implementation should not do anything with the result of any of
    the result supplier, accumulator, or combiner functions other than to
    pass them again to the accumulator, combiner, or finisher functions,
    or return them to the caller of the reduction operation.
    If a result is passed to the combiner or finisher
    function, and the same object is not returned from that function, it is
    never used again.
    Once a result is passed to the combiner or finisher function, it
    is never passed to the accumulator function again.
    For non-concurrent collectors, any result returned from the result
    supplier, accumulator, or combiner functions must be serially
    thread-confined.  This enables collection to occur in parallel without
    the Collector needing to implement any additional synchronization.
    The reduction implementation must manage that the input is properly
    partitioned, that partitions are processed in isolation, and combining
    happens only after accumulation is complete.
    For concurrent collectors, an implementation is free to (but not
    required to) implement reduction concurrently.  A concurrent reduction
    is one where the accumulator function is called concurrently from
    multiple threads, using the same concurrently-modifiable result container,
    rather than keeping the result isolated during accumulation.
    A concurrent reduction should only be applied if the collector has the
    Collector.Characteristics.UNORDERED characteristics or if the
    originating data is unordered.


In addition to the predefined implementations in Collectors, the
static factory methods of(Supplier, BiConsumer, BinaryOperator, Characteristics...)
can be used to construct collectors.  For example, you could create a collector
that accumulates widgets into a TreeSet with:



    Collector<Widget, ?, TreeSet<Widget>> intoSet =
        Collector.of(TreeSet::new, TreeSet::add,
                     (left, right) -> { left.addAll(right); return left; });

(This behavior is also implemented by the predefined collector
Collectors.toCollection(Supplier)).

// Accumulate names into a List
List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());

// Accumulate names into a TreeSet
Set<String> set = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));

// Convert elements to strings and concatenate them, separated by commas
String joined = things.stream()
                      .map(Object::toString)
                      .collect(Collectors.joining(", "));

// Compute sum of salaries of employee
int total = employees.stream()
                     .collect(Collectors.summingInt(Employee::getSalary)));

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

// Compute sum of salaries by department
Map<Department, Integer> totalByDept
    = employees.stream()
               .collect(Collectors.groupingBy(Employee::getDepartment,
                                              Collectors.summingInt(Employee::getSalary)));

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

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 collectors to perform
common mutable reduction tasks:



    // Accumulate names into a List
    List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());

    // Accumulate names into a TreeSet
    Set<String> set = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));

    // Convert elements to strings and concatenate them, separated by commas
    String joined = things.stream()
                          .map(Object::toString)
                          .collect(Collectors.joining(", "));

    // Compute sum of salaries of employee
    int total = employees.stream()
                         .collect(Collectors.summingInt(Employee::getSalary)));

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

    // Compute sum of salaries by department
    Map<Department, Integer> totalByDept
        = employees.stream()
                   .collect(Collectors.groupingBy(Employee::getDepartment,
                                                  Collectors.summingInt(Employee::getSalary)));

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

double sum = widgets.stream()
                    .filter(w -> w.getColor() == RED)
                    .mapToDouble(w -> w.getWeight())
                    .sum();

A sequence of primitive double-valued elements supporting sequential and parallel
aggregate operations.  This is the double primitive specialization of
Stream.

The following example illustrates an aggregate operation using
Stream and DoubleStream, computing the sum of the weights of the
red widgets:



    double sum = widgets.stream()
                        .filter(w -> w.getColor() == RED)
                        .mapToDouble(w -> w.getWeight())
                        .sum();

See the class documentation for Stream and the package documentation
for java.util.stream for additional
specification of streams, stream operations, stream pipelines, and
parallelism.

A mutable builder for a DoubleStream.

A stream builder has a lifecycle, which starts in a building
phase, during which elements can be added, and then transitions to a built
phase, after which elements may not be added.  The built phase
begins when the build() method is called, which creates an
ordered stream whose elements are the elements that were added to the
stream builder, in the order they were added.

int sum = widgets.stream()
                 .filter(w -> w.getColor() == RED)
                 .mapToInt(w -> w.getWeight())
                 .sum();

A sequence of primitive int-valued elements supporting sequential and parallel
aggregate operations.  This is the int primitive specialization of
Stream.

The following example illustrates an aggregate operation using
Stream and IntStream, computing the sum of the weights of the
red widgets:



    int sum = widgets.stream()
                     .filter(w -> w.getColor() == RED)
                     .mapToInt(w -> w.getWeight())
                     .sum();

See the class documentation for Stream and the package documentation
for java.util.stream for additional
specification of streams, stream operations, stream pipelines, and
parallelism.

A mutable builder for an IntStream.

A stream builder has a lifecycle, which starts in a building
phase, during which elements can be added, and then transitions to a built
phase, after which elements may not be added.  The built phase
begins when the build() method is called, which creates an
ordered stream whose elements are the elements that were added to the
stream builder, in the order they were added.

long sum = widgets.stream()
                  .filter(w -> w.getColor() == RED)
                  .mapToLong(w -> w.getWeight())
                  .sum();

A sequence of primitive long-valued elements supporting sequential and parallel
aggregate operations.  This is the long primitive specialization of
Stream.

The following example illustrates an aggregate operation using
Stream and LongStream, computing the sum of the weights of the
red widgets:



    long sum = widgets.stream()
                      .filter(w -> w.getColor() == RED)
                      .mapToLong(w -> w.getWeight())
                      .sum();

See the class documentation for Stream and the package documentation
for java.util.stream for additional
specification of streams, stream operations, stream pipelines, and
parallelism.

A mutable builder for a LongStream.

A stream builder has a lifecycle, which starts in a building
phase, during which elements can be added, and then transitions to a built
phase, after which elements may not be added.  The built phase begins
begins when the build() method is called, which creates an
ordered stream whose elements are the elements that were added to the
stream builder, in the order they were added.

int sum = widgets.stream()
                 .filter(w -> w.getColor() == RED)
                 .mapToInt(w -> w.getWeight())
                 .sum();

A sequence of elements supporting sequential and parallel aggregate
operations.  The following example illustrates an aggregate operation using
Stream and IntStream:



    int sum = widgets.stream()
                     .filter(w -> w.getColor() == RED)
                     .mapToInt(w -> w.getWeight())
                     .sum();

In this example, widgets is a Collection<Widget>.  We create
a stream of Widget objects via Collection.stream(),
filter it to produce a stream containing only the red widgets, and then
transform it into a stream of int values representing the weight of
each red widget. Then this stream is summed to produce a total weight.

In addition to Stream, which is a stream of object references,
there are primitive specializations for IntStream, LongStream,
and DoubleStream, all of which are referred to as "streams" and
conform to the characteristics and restrictions described here.

To perform a computation, stream
operations are composed into a
stream 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 more intermediate operations (which transform a
stream into another stream, such as filter(Predicate)), and a
terminal operation (which produces a result or side-effect, such
as count() or forEach(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, the BaseStream.iterator() and BaseStream.spliterator() operations
can be used to perform a controlled traversal.

A stream pipeline, like the "widgets" example above, can be viewed as
a query on the stream source.  Unless the source was explicitly
designed for concurrent modification (such as a ConcurrentHashMap),
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 expression w -> w.getWeight() passed to
mapToInt in the example above.  To preserve correct behavior,
these behavioral parameters:

must be non-interfering
(they do not modify the stream source); and
in most cases must be stateless
(their result should not depend on any state that might change during execution
of the stream pipeline).


Such parameters are always instances of a
functional interface such
as Function, and are often lambda expressions or
method references.  Unless otherwise specified these parameters must be
non-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 throw IllegalStateException
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 a BaseStream.close() method and implement AutoCloseable,
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
by Files.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 a try-with-resources statement.)

Stream pipelines may execute either sequentially or in
parallel.  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,
and Collection.parallelStream() creates
a parallel one.)  This choice of execution mode may be modified by the
BaseStream.sequential() or BaseStream.parallel() methods, and may be queried with
the BaseStream.isParallel() method.

A mutable builder for a Stream.  This allows the creation of a
Stream by generating elements individually and adding them to the
Builder (without the copying overhead that comes from using
an ArrayList as a temporary buffer.)

A stream builder has a lifecycle, which starts in a building
phase, during which elements can be added, and then transitions to a built
phase, after which elements may not be added.  The built phase begins
when the build() method is called, which creates an ordered
Stream whose elements are the elements that were added to the stream
builder, in the order they were added.

Low-level utility methods for creating and manipulating streams.

This class is mostly for library writers presenting stream views
of data structures; most static stream methods intended for end users are in
the various Stream classes.