RefStreams (net.sourceforge.streamsupport:streamsupport 1.5.2 API)

java.lang.Object
- java8.util.stream.RefStreams

```
public final class RefStreams
extends Object
```
A place for static default implementations of the new Java 8/9 static interface methods and default interface methods (takeWhile(), dropWhile()) in the Stream interface.

Method Summary

All Methods Static Methods Concrete Methods
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>`	`dropWhile(Stream<? extends T> stream, Predicate<? super T> predicate)` Returns, if the passed stream is ordered, a stream consisting of the remaining elements of the passed stream after dropping the longest prefix of elements that match the given predicate.
`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<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`.
`static <T> Stream<T>`	`takeWhile(Stream<? extends T> stream, Predicate<? super T> predicate)` Returns, if the passed stream is ordered, a stream consisting of the longest prefix of elements taken from the passed stream that match the given predicate.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - takeWhile
```
public static <T> Stream<T> takeWhile(Stream<? extends T> stream,
                                      Predicate<? super T> predicate)
```
    Returns, if the passed stream is ordered, a stream consisting of the longest prefix of elements taken from the passed stream that match the given predicate. Otherwise returns, if the passed stream is unordered, a stream consisting of a subset of elements taken from the passed stream that match the given predicate.
    If the passed stream is ordered then the longest prefix is a contiguous sequence of elements of the passed stream that match the given predicate. The first element of the sequence is the first element of the passed stream, and the element immediately following the last element of the sequence does not match the given predicate.
    If the passed stream is unordered, and some (but not all) elements of the passed stream match the given predicate, then the behavior of this operation is nondeterministic; it is free to take any subset of matching elements (which includes the empty set).
    Independent of whether the passed stream is ordered or unordered if all elements of the passed stream match the given predicate then this operation takes all elements (the result is the same as the input), or if no elements of the passed stream match the given predicate then no elements are taken (the result is an empty stream).
    This is a short-circuiting stateful intermediate operation.
    Implementation Requirements:
    The default implementation obtains the spliterator of the passed stream, wraps that spliterator so as to support the semantics of this operation on traversal, and returns a new stream associated with the wrapped spliterator. The returned stream preserves the execution characteristics of the passed stream (namely parallel or sequential execution as per isParallel()) but the wrapped spliterator may choose to not support splitting. When the returned stream is closed, the close handlers for both the returned and the passed stream are invoked.
    API Note:
    While takeWhile() is generally a cheap operation on sequential stream pipelines, it can be quite expensive on ordered parallel pipelines, since the operation is constrained to return not just any valid prefix, but the longest prefix of elements in the encounter order. Using an unordered stream source (such as generate(Supplier)) or removing the ordering constraint with unordered() may result in significant speedups of takeWhile() 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 with takeWhile() in parallel pipelines, switching to sequential execution with sequential() may improve performance.
    A use-case for stream cancellation is executing a stream pipeline for a certain duration. The following example will calculate as many probable primes as is possible, in parallel, during 5 seconds:
```
     long t = System.currentTimeMillis();
     List<BigInteger> pps = RefStreams
         .generate(() -> BigInteger.probablePrime(1024, ThreadLocalRandom.current()))
         .parallel()
         .takeWhile(e -> (System.currentTimeMillis() - t) < TimeUnit.SECONDS.toMillis(5))
         .collect(toList());

 
```
    Type Parameters:
    
    T - the type of the stream elements
    
    Parameters:
    
    stream - the stream to wrap for the takeWhile() operation
    
    predicate - a non-interfering, predicate to apply elements to determine the longest prefix of elements.
    
    Returns:
    
    the new stream
    
    Since:
    
    9
  - dropWhile
```
public static <T> Stream<T> dropWhile(Stream<? extends T> stream,
                                      Predicate<? super T> predicate)
```
    Returns, if the passed stream is ordered, a stream consisting of the remaining elements of the passed stream after dropping the longest prefix of elements that match the given predicate. Otherwise returns, if the passed stream is unordered, a stream consisting of the remaining elements of the passed stream after dropping a subset of elements that match the given predicate.
    If the passed stream is ordered then the longest prefix is a contiguous sequence of elements of the passed stream that match the given predicate. The first element of the sequence is the first element of the passed stream, and the element immediately following the last element of the sequence does not match the given predicate.
    If the passed stream is unordered, and some (but not all) elements of the passed stream match the given predicate, then the behavior of this operation is nondeterministic; it is free to drop any subset of matching elements (which includes the empty set).
    Independent of whether the passed stream is ordered or unordered if all elements of the passed stream match the given predicate then this operation drops all elements (the result is an empty stream), or if no elements of the passed stream match the given predicate then no elements are dropped (the result is the same as the input).
    This is a stateful intermediate operation.
    Implementation Requirements:
    The default implementation obtains the spliterator of the passed stream, wraps that spliterator so as to support the semantics of this operation on traversal, and returns a new stream associated with the wrapped spliterator. The returned stream preserves the execution characteristics of the passed stream (namely parallel or sequential execution as per isParallel()) but the wrapped spliterator may choose to not support splitting. When the returned stream is closed, the close handlers for both the returned and the passed stream are invoked.
    API Note:
    While dropWhile() is generally a cheap operation on sequential stream pipelines, it can be quite expensive on ordered parallel pipelines, since the operation is constrained to return not just any valid prefix, but the longest prefix of elements in the encounter order. Using an unordered stream source (such as generate(Supplier)) or removing the ordering constraint with unordered() may result in significant speedups of dropWhile() 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 with dropWhile() in parallel pipelines, switching to sequential execution with sequential() may improve performance.
    
    Type Parameters:
    
    T - the type of the stream elements
    
    Parameters:
    
    stream - the stream to wrap for the dropWhile() operation
    
    predicate - a non-interfering, stateless predicate to apply elements to determine the longest prefix of elements.
    
    Returns:
    
    the new stream
    
    Since:
    
    9
  - 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<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.
    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.
    
    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

Class RefStreams

Method Summary

Methods inherited from class java.lang.Object

Method Detail

takeWhile

dropWhile

builder

empty

of

ofNullable

of

iterate

iterate

generate

concat