Please note that the specifications and other information contained herein are not final and are subject to change. The information is being made available to you solely for purpose of evaluation.
Java™ Platform
Standard Ed. 8

DRAFT ea-b00
compact1, compact2, compact3
java.util.stream

Interface Stream<T>

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      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) 
      long count()
      Return the count of elements in this stream.
      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.
      <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()
      Returns 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
      Iterator<T> iterator()
      Returns 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.
      Optional<T> max(Comparator<? super T> comparator)
      Return the maximal element of this stream according to the provided Comparator.
      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()
      Produces 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()
      Produces 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()
      Returns 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.
      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
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • flatMap

        <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
        Returns:
        the new stream
        API Note
        For example, if @{code orders} is a stream of purchase orders, and each purchase order contains a collection of line items, then the following transforms the stream of orders into a stream of line items:
             orderStream.flatMap(order -> order.getLineItems().stream())...
         

        This implementation is likely to be less efficient than the other form of flatMap(FlatMapper), and is provided for convenience.

      • 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
        Returns:
        the new stream
        API Note
        A FlatMapper is like a function that received an element to transform, and a Consumer into which to deposit zero or more values corresponding to that element. For example, to map a stream of strings into a stream of the characters in those strings, you would do:
             stringStream.flatMap((elt, destination) -> {
                                      for (i=0; i < elt.length(); i++)
                                          destination.accept(charAt(i));
                                  })
                         ...
         
        Implementation Note
        This form of flatMap is usually less convenient to use than the flatMap(Function) form, but is often considerably more efficient because it eliminates the overhead of stream construction and traversal.
      • 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
        Returns:
        the new stream
        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
        Returns:
        the new stream
        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
        Returns:
        the new stream
        See Also:
        flatMap(FlatMapper)
      • 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.
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • 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.
        Parameters:
        consumer - The Consumer to receive the elements
        Returns:
        the new stream
        API Note
        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.

      • 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.
        Returns:
        the new stream
      • 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.
        Returns:
        the new stream
      • 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
        Returns:
        the new stream
      • toArray

        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
        API Note
        Sum, min, max, average, and string concatenation are all special cases of reduction. Adding a stream of numbers can be expressed as:
             Integer sum = integers.reduce(0, (a, b) -> a+b);
         
        or more compactly:
             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.

      • 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)
        API Note
        Many reductions using this form can be represented more simply by an explicit combination of map and reduce operations. The reducer function acts as a fused mapper and reducer, which can sometimes be more efficient than separate mapping and reduction, such as in the case where knowing the previously reduced value allows you to avoid some computation.
      • 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 by replacing the result. This produces a result equivalent to:
             R result = resultFactory.get();
             for (T element : this stream)
                 accumulator.accept(result, element);
             return result;
         
        Like reduce(Object, BinaryOperator), collect operations can be parallelized without requiring additional sychronization.
        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
        API Note
        There are many existing classes in the JDK whose signatures are a good match for use as arguments to collect(). For example, the following will accumulate strings into an ArrayList:
             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();
         
      • 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
        API Note
        The following will accumulate strings into an ArrayList:
             List<String> asList = stringStream.collect(Collectors.toList());
         }
        The following will classify Person objects by city:
             Map<String, Collection<Person>> peopleByCity
                 = personStream.collect(Collectors.groupBy(Person::getCity));
         
        The following will classify Person objects by state and city, cascading two Collectors together:
             Map<String, Map<String, Collection<Person>>> peopleByStateAndCity
                 = personStream.collect(Collectors.groupBy(Person::getState,
                                                           Collectors.groupBy(Person::getCity)));
         
      • collectUnordered

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

        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

        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
      • count

        long count()
        Return the count of elements in this stream.
        Returns:
        The count of elements in 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

        Iterator<T> iterator()
        Returns an iterator for the elements of this stream. This is a terminal operation.
        Returns:
        the element iterator for this stream
      • spliterator

        Spliterator<T> spliterator()
        Returns 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()
        Returns 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()
        Produces 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()
        Produces 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
Java™ Platform
Standard Ed. 8

DRAFT ea-b00

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

DRAFT ea-b00