java8.util.stream

Class RefStreams

java.lang.Object

java8.util.stream.RefStreams

public final class RefStreams
extends Object

A place for the implementations of the new Java 8/9 static interface methods in the Stream interface.

Method Summary

Modifier and Type	Method and Description
static <T> Stream.Builder<T>	builder() Returns a builder for a 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.
static <T> Stream<T>	empty() Returns an empty sequential Stream.
static <T> Stream<T>	generate(Supplier<? extends T> s) Returns an infinite sequential unordered Stream where each element is generated by the provided Supplier.
static <T,S extends T> Stream<T>	iterate(S seed, Predicate<? super S> hasNext, UnaryOperator<S> next) Returns a sequential ordered Stream produced by iterative application of the given next function to an initial element, conditioned on satisfying the given hasNext predicate.
static <T,S extends T> Stream<T>	iterate(S seed, UnaryOperator<S> f) Returns an infinite sequential ordered Stream produced by iterative application of a function f to an initial element seed, producing a Stream consisting of seed, f(seed), f(f(seed)), etc.
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.
static <T> Stream<T>	ofNullable(T t) Returns a sequential Stream containing a single element, if non-null, otherwise returns an empty Stream.

Methods inherited from class java.lang.Object

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

Method Detail

builder

public static <T> Stream.Builder<T> builder()

Returns a builder for a Stream.

Type Parameters:

T - type of elements

Returns:

a stream builder

empty

public static <T> Stream<T> empty()

Returns an empty sequential Stream.

Type Parameters:

T - the type of stream elements

Returns:

an empty sequential stream

of

public static <T> Stream<T> of(T t)

Returns a sequential Stream containing a single element.

Type Parameters:

T - the type of stream elements

Parameters:

t - the single element

Returns:

a singleton sequential stream

ofNullable

public static <T> Stream<T> ofNullable(T t)

Returns a sequential Stream containing a single element, if non-null, otherwise returns an empty Stream.

Type Parameters:

T - the type of stream elements

Parameters:

t - the single element

Returns:

a stream with a single element if the specified element is non-null, otherwise an empty stream

Since:

9

of

public static <T> Stream<T> of(T... values)

Returns a sequential ordered Stream whose elements are the specified values.

Type Parameters:

T - the type of stream elements

Parameters:

values - the elements of the new stream

Returns:

the new stream

iterate

public static <T,S extends T> Stream<T> iterate(S seed,
                                                UnaryOperator<S> f)

Returns an infinite sequential ordered Stream produced by iterative application of a function f to an initial element seed, producing a Stream consisting of seed, f(seed), f(f(seed)), etc.

The first element (position 0) in the Stream will be the provided seed. For n > 0, the element at position n, will be the result of applying the function f to the element at position n - 1.

The action of applying f for one element happens-before the action of applying f for subsequent elements. For any given element the action may be performed in whatever thread the library chooses.

Type Parameters:

S - the type of the operand and seed, a subtype of T

T - the type of stream elements

Parameters:

seed - the initial element

f - a function to be applied to the previous element to produce a new element

Returns:

a new sequential Stream

iterate

public static <T,S extends T> Stream<T> iterate(S seed,
                                                Predicate<? super S> hasNext,
                                                UnaryOperator<S> next)

Returns a sequential ordered Stream produced by iterative application of the given next function to an initial element, conditioned on satisfying the given hasNext predicate. The stream terminates as soon as the hasNext predicate returns false.

RefStreams.iterate should produce the same sequence of elements as produced by the corresponding for-loop:

     for (T index=seed; hasNext.test(index); index = next.apply(index)) { 
         ... 
     }
 

The resulting sequence may be empty if the hasNext predicate does not hold on the seed value. Otherwise the first element will be the supplied seed value, the next element (if present) will be the result of applying the next function to the seed value, and so on iteratively until the hasNext predicate indicates that the stream should terminate.

The action of applying the hasNext predicate to an element happens-before the action of applying the next function to that element. The action of applying the next function for one element happens-before the action of applying the hasNext predicate for subsequent elements. For any given element an action may be performed in whatever thread the library chooses.

Type Parameters:

S - the type of the operand, predicate input and seed, a subtype of T

T - the type of stream elements

Parameters:

seed - the initial element

hasNext - a predicate to apply to elements to determine when the stream must terminate

next - a function to be applied to the previous element to produce a new element

Returns:

a new sequential Stream

Since:

9

generate

public static <T> Stream<T> generate(Supplier<? extends T> s)

Returns an infinite sequential unordered Stream where each element is generated by the provided Supplier. This is suitable for generating constant streams, streams of random elements, etc.

Type Parameters:

T - the type of stream elements

Parameters:

s - the Supplier of generated elements

Returns:

a new infinite sequential unordered Stream

concat

public 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. The resulting stream is ordered if both of the input streams are ordered, and parallel if either of the input streams is parallel. When the resulting stream is closed, the close handlers for both input streams are invoked.

This method operates on the two input streams and binds each stream to its source. As a result subsequent modifications to an input stream source may not be reflected in the concatenated stream result.

Implementation Note:
Use caution when constructing streams from repeated concatenation. Accessing an element of a deeply concatenated stream can result in deep call chains, or even StackOverflowError.

Subsequent changes to the sequential/parallel execution mode of the returned stream are not guaranteed to be propagated to the input streams.

API Note:
To preserve optimization opportunities this method binds each stream to its source and accepts only two streams as parameters. For example, the exact size of the concatenated stream source can be computed if the exact size of each input stream source is known. To concatenate more streams without binding, or without nested calls to this method, try creating a stream of streams and flat-mapping with the identity function, for example:

     Stream<T> concat = RefStreams.of(s1, s2, s3, s4).flatMap(s -> s);
 

Type Parameters:

T - The type of stream elements

Parameters:

a - the first stream

b - the second stream

Returns:

the concatenation of the two input streams