Package com.google.common.collect

Class Streams

  • @GwtCompatible
public final class Streams
extends java.lang.Object
    Static utility methods related to Stream instances.
    Since:
    21.0

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static java.util.stream.DoubleStream concat​(java.util.stream.DoubleStream... streams)
      Returns a DoubleStream containing the elements of the first stream, followed by the elements of the second stream, and so on.
      static java.util.stream.IntStream concat​(java.util.stream.IntStream... streams)
      Returns an IntStream containing the elements of the first stream, followed by the elements of the second stream, and so on.
      static java.util.stream.LongStream concat​(java.util.stream.LongStream... streams)
      Returns a LongStream containing the elements of the first stream, followed by the elements of the second stream, and so on.
      static <T extends @Nullable java.lang.Object>
      java.util.stream.Stream<T>      		 concat​(java.util.stream.Stream<? extends T>... streams)
      Returns a Stream containing the elements of the first stream, followed by the elements of the second stream, and so on.
      static java.util.OptionalDouble findLast​(java.util.stream.DoubleStream stream)
      Returns the last element of the specified stream, or OptionalDouble.empty() if the stream is empty.
      static java.util.OptionalInt findLast​(java.util.stream.IntStream stream)
      Returns the last element of the specified stream, or OptionalInt.empty() if the stream is empty.
      static java.util.OptionalLong findLast​(java.util.stream.LongStream stream)
      Returns the last element of the specified stream, or OptionalLong.empty() if the stream is empty.
      static <T> java.util.Optional<T> findLast​(java.util.stream.Stream<T> stream)
      Returns the last element of the specified stream, or Optional.empty() if the stream is empty.
      static <A extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object>
      void      		 forEachPair​(java.util.stream.Stream<A> streamA, java.util.stream.Stream<B> streamB, java.util.function.BiConsumer<? super A,​? super B> consumer)
      Invokes consumer once for each pair of corresponding elements in streamA and streamB.
      static <R extends @Nullable java.lang.Object>
      java.util.stream.Stream<R>      		 mapWithIndex​(java.util.stream.DoubleStream stream, Streams.DoubleFunctionWithIndex<R> function)
      Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream.
      static <R extends @Nullable java.lang.Object>
      java.util.stream.Stream<R>      		 mapWithIndex​(java.util.stream.IntStream stream, Streams.IntFunctionWithIndex<R> function)
      Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream.
      static <R extends @Nullable java.lang.Object>
      java.util.stream.Stream<R>      		 mapWithIndex​(java.util.stream.LongStream stream, Streams.LongFunctionWithIndex<R> function)
      Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream.
      static <T extends @Nullable java.lang.Object,​R extends @Nullable java.lang.Object>
      java.util.stream.Stream<R>      		 mapWithIndex​(java.util.stream.Stream<T> stream, Streams.FunctionWithIndex<? super T,​? extends R> function)
      Returns a stream consisting of the results of applying the given function to the elements of stream and their indices in the stream.
      static <T> java.util.stream.Stream<T> stream​(Optional<T> optional)
      If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.
      static <T extends @Nullable java.lang.Object>
      java.util.stream.Stream<T>      		 stream​(java.lang.Iterable<T> iterable)
      Returns a sequential Stream of the contents of iterable, delegating to Collection.stream() if possible.
      static <T extends @Nullable java.lang.Object>
      java.util.stream.Stream<T>      		 stream​(java.util.Collection<T> collection)
      Deprecated.
      There is no reason to use this; just invoke collection.stream() directly.
      static <T extends @Nullable java.lang.Object>
      java.util.stream.Stream<T>      		 stream​(java.util.Iterator<T> iterator)
      Returns a sequential Stream of the remaining contents of iterator.
      static <T> java.util.stream.Stream<T> stream​(java.util.Optional<T> optional)
      If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.
      static java.util.stream.DoubleStream stream​(java.util.OptionalDouble optional)
      If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.
      static java.util.stream.IntStream stream​(java.util.OptionalInt optional)
      If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.
      static java.util.stream.LongStream stream​(java.util.OptionalLong optional)
      If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.
      static <A extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object,​R extends @Nullable java.lang.Object>
      java.util.stream.Stream<R>      		 zip​(java.util.stream.Stream<A> streamA, java.util.stream.Stream<B> streamB, java.util.function.BiFunction<? super A,​? super B,​R> function)
      Returns a stream in which each element is the result of passing the corresponding element of each of streamA and streamB to function.

      • Methods inherited from class java.lang.Object

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

    • Method Detail

      • stream

        public static <T extends @Nullable java.lang.Object> java.util.stream.Stream<T> stream​(java.lang.Iterable<T> iterable)
        Returns a sequential Stream of the contents of iterable, delegating to Collection.stream() if possible.

      • stream

        @Deprecated
@InlineMe(replacement="collection.stream()")
public static <T extends @Nullable java.lang.Object> java.util.stream.Stream<T> stream​(java.util.Collection<T> collection)
        Deprecated.
        There is no reason to use this; just invoke collection.stream() directly.
        Returns Collection.stream().

      • stream

        public static <T extends @Nullable java.lang.Object> java.util.stream.Stream<T> stream​(java.util.Iterator<T> iterator)
        Returns a sequential Stream of the remaining contents of iterator. Do not use iterator directly after passing it to this method.

      • stream

        public static <T> java.util.stream.Stream<T> stream​(Optional<T> optional)
        If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.

      • stream

        @Beta
@InlineMe(replacement="optional.stream()")
public static <T> java.util.stream.Stream<T> stream​(java.util.Optional<T> optional)
        If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.

        Java 9 users: use optional.stream() instead.

      • stream

        @Beta
@InlineMe(replacement="optional.stream()")
public static java.util.stream.IntStream stream​(java.util.OptionalInt optional)
        If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.

        Java 9 users: use optional.stream() instead.

      • stream

        @Beta
@InlineMe(replacement="optional.stream()")
public static java.util.stream.LongStream stream​(java.util.OptionalLong optional)
        If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.

        Java 9 users: use optional.stream() instead.

      • stream

        @Beta
@InlineMe(replacement="optional.stream()")
public static java.util.stream.DoubleStream stream​(java.util.OptionalDouble optional)
        If a value is present in optional, returns a stream containing only that element, otherwise returns an empty stream.

        Java 9 users: use optional.stream() instead.

      • concat

        @SafeVarargs
public static <T extends @Nullable java.lang.Object> java.util.stream.Stream<T> concat​(java.util.stream.Stream<? extends T>... streams)
        Returns a Stream containing the elements of the first stream, followed by the elements of the second stream, and so on.

        This is equivalent to Stream.of(streams).flatMap(stream -> stream), but the returned stream may perform better.

        See Also:
        Stream.concat(Stream, Stream)

      • concat

        public static java.util.stream.IntStream concat​(java.util.stream.IntStream... streams)
        Returns an IntStream containing the elements of the first stream, followed by the elements of the second stream, and so on.

        This is equivalent to Stream.of(streams).flatMapToInt(stream -> stream), but the returned stream may perform better.

        See Also:
        IntStream.concat(IntStream, IntStream)

      • concat

        public static java.util.stream.LongStream concat​(java.util.stream.LongStream... streams)
        Returns a LongStream containing the elements of the first stream, followed by the elements of the second stream, and so on.

        This is equivalent to Stream.of(streams).flatMapToLong(stream -> stream), but the returned stream may perform better.

        See Also:
        LongStream.concat(LongStream, LongStream)

      • concat

        public static java.util.stream.DoubleStream concat​(java.util.stream.DoubleStream... streams)
        Returns a DoubleStream containing the elements of the first stream, followed by the elements of the second stream, and so on.

        This is equivalent to Stream.of(streams).flatMapToDouble(stream -> stream), but the returned stream may perform better.

        See Also:
        DoubleStream.concat(DoubleStream, DoubleStream)

      • zip

        @Beta
public static <A extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object,​R extends @Nullable java.lang.Object> java.util.stream.Stream<R> zip​(java.util.stream.Stream<A> streamA,
                                                                                                                                                                          java.util.stream.Stream<B> streamB,
                                                                                                                                                                          java.util.function.BiFunction<? super A,​? super B,​R> function)
        Returns a stream in which each element is the result of passing the corresponding element of each of streamA and streamB to function.

        For example: 

        
 Streams.zip(
   Stream.of("foo1", "foo2", "foo3"),
   Stream.of("bar1", "bar2"),
   (arg1, arg2) -> arg1 + ":" + arg2)

        will return Stream.of("foo1:bar1", "foo2:bar2").

        The resulting stream will only be as long as the shorter of the two input streams; if one stream is longer, its extra elements will be ignored.

        Note that if you are calling Stream.forEach(java.util.function.Consumer<? super T>) on the resulting stream, you might want to consider using forEachPair(java.util.stream.Stream<A>, java.util.stream.Stream<B>, java.util.function.BiConsumer<? super A, ? super B>) instead of this method.

        Performance note: The resulting stream is not efficiently splittable. This may harm parallel performance.

      • forEachPair

        @Beta
public static <A extends @Nullable java.lang.Object,​B extends @Nullable java.lang.Object> void forEachPair​(java.util.stream.Stream<A> streamA,
                                                                                                                 java.util.stream.Stream<B> streamB,
                                                                                                                 java.util.function.BiConsumer<? super A,​? super B> consumer)
        Invokes consumer once for each pair of corresponding elements in streamA and streamB. If one stream is longer than the other, the extra elements are silently ignored. Elements passed to the consumer are guaranteed to come from the same position in their respective source streams. For example: 
        
 Streams.forEachPair(
   Stream.of("foo1", "foo2", "foo3"),
   Stream.of("bar1", "bar2"),
   (arg1, arg2) -> System.out.println(arg1 + ":" + arg2)

        will print: 

        
 foo1:bar1
 foo2:bar2

        Warning: If either supplied stream is a parallel stream, the same correspondence between elements will be made, but the order in which those pairs of elements are passed to the consumer is not defined.

        Note that many usages of this method can be replaced with simpler calls to zip(java.util.stream.Stream<A>, java.util.stream.Stream<B>, java.util.function.BiFunction<? super A, ? super B, R>). This method behaves equivalently to zipping the stream elements into temporary pair objects and then using Stream.forEach(java.util.function.Consumer<? super T>) on that stream.

        Since:
        22.0

      • mapWithIndex

        public static <T extends @Nullable java.lang.Object,​R extends @Nullable java.lang.Object> java.util.stream.Stream<R> mapWithIndex​(java.util.stream.Stream<T> stream,
                                                                                                                                        Streams.FunctionWithIndex<? super T,​? extends R> function)
        Returns a stream consisting of the results of applying the given function to the elements of stream and their indices in the stream. For example, 
        
 mapWithIndex(
     Stream.of("a", "b", "c"),
     (e, index) -> index + ":" + e)

        would return Stream.of("0:a", "1:b", "2:c").

        The resulting stream is efficiently splittable if and only if stream was efficiently splittable and its underlying spliterator reported Spliterator.SUBSIZED. This is generally the case if the underlying stream comes from a data structure supporting efficient indexed random access, typically an array or list.

        The order of the resulting stream is defined if and only if the order of the original stream was defined.

      • mapWithIndex

        public static <R extends @Nullable java.lang.Object> java.util.stream.Stream<R> mapWithIndex​(java.util.stream.IntStream stream,
                                                                                             Streams.IntFunctionWithIndex<R> function)
        Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream. For example, 
        
 mapWithIndex(
     IntStream.of(10, 11, 12),
     (e, index) -> index + ":" + e)

        ...would return Stream.of("0:10", "1:11", "2:12").

        The resulting stream is efficiently splittable if and only if stream was efficiently splittable and its underlying spliterator reported Spliterator.SUBSIZED. This is generally the case if the underlying stream comes from a data structure supporting efficient indexed random access, typically an array or list.

        The order of the resulting stream is defined if and only if the order of the original stream was defined.

      • mapWithIndex

        public static <R extends @Nullable java.lang.Object> java.util.stream.Stream<R> mapWithIndex​(java.util.stream.LongStream stream,
                                                                                             Streams.LongFunctionWithIndex<R> function)
        Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream. For example, 
        
 mapWithIndex(
     LongStream.of(10, 11, 12),
     (e, index) -> index + ":" + e)

        ...would return Stream.of("0:10", "1:11", "2:12").

        The resulting stream is efficiently splittable if and only if stream was efficiently splittable and its underlying spliterator reported Spliterator.SUBSIZED. This is generally the case if the underlying stream comes from a data structure supporting efficient indexed random access, typically an array or list.

        The order of the resulting stream is defined if and only if the order of the original stream was defined.

      • mapWithIndex

        public static <R extends @Nullable java.lang.Object> java.util.stream.Stream<R> mapWithIndex​(java.util.stream.DoubleStream stream,
                                                                                             Streams.DoubleFunctionWithIndex<R> function)
        Returns a stream consisting of the results of applying the given function to the elements of stream and their indexes in the stream. For example, 
        
 mapWithIndex(
     DoubleStream.of(0.0, 1.0, 2.0)
     (e, index) -> index + ":" + e)

        ...would return Stream.of("0:0.0", "1:1.0", "2:2.0").

        The resulting stream is efficiently splittable if and only if stream was efficiently splittable and its underlying spliterator reported Spliterator.SUBSIZED. This is generally the case if the underlying stream comes from a data structure supporting efficient indexed random access, typically an array or list.

        The order of the resulting stream is defined if and only if the order of the original stream was defined.

      • findLast

        public static <T> java.util.Optional<T> findLast​(java.util.stream.Stream<T> stream)
        Returns the last element of the specified stream, or Optional.empty() if the stream is empty.

        Equivalent to stream.reduce((a, b) -> b), but may perform significantly better. This method's runtime will be between O(log n) and O(n), performing better on efficiently splittable streams.

        If the stream has nondeterministic order, this has equivalent semantics to Stream.findAny() (which you might as well use).

        Throws:
        java.lang.NullPointerException - if the last element of the stream is null
        See Also:
        Stream.findFirst()

      • findLast

        public static java.util.OptionalInt findLast​(java.util.stream.IntStream stream)
        Returns the last element of the specified stream, or OptionalInt.empty() if the stream is empty.

        Equivalent to stream.reduce((a, b) -> b), but may perform significantly better. This method's runtime will be between O(log n) and O(n), performing better on efficiently splittable streams.

        Throws:
        java.lang.NullPointerException - if the last element of the stream is null
        See Also:
        IntStream.findFirst()

      • findLast

        public static java.util.OptionalLong findLast​(java.util.stream.LongStream stream)
        Returns the last element of the specified stream, or OptionalLong.empty() if the stream is empty.

        Equivalent to stream.reduce((a, b) -> b), but may perform significantly better. This method's runtime will be between O(log n) and O(n), performing better on efficiently splittable streams.

        Throws:
        java.lang.NullPointerException - if the last element of the stream is null
        See Also:
        LongStream.findFirst()

      • findLast

        public static java.util.OptionalDouble findLast​(java.util.stream.DoubleStream stream)
        Returns the last element of the specified stream, or OptionalDouble.empty() if the stream is empty.

        Equivalent to stream.reduce((a, b) -> b), but may perform significantly better. This method's runtime will be between O(log n) and O(n), performing better on efficiently splittable streams.

        Throws:
        java.lang.NullPointerException - if the last element of the stream is null
        See Also:
        DoubleStream.findFirst()