net.sf.staccatocommons.collections.stream
Class Streams

java.lang.Object
  net.sf.staccatocommons.collections.stream.Streams

public class Streams
extends Object

Class methods for creating very simple Streams wrapping existing classes from the Java collections framework, specifiying its elements and

Author:

flbulgarelli

Method Summary

static <A> Stream<A>	cons(A... elements) Creates a new Stream that retrieves the elements from the given array.
static <A> Stream<A>	cons(A element) Creates a new Stream that will retrieve just the given element
static <A> Stream<A>	cons(A head, Stream<? extends A> tail) Creates a new Stream that retrieves elements from a head, and another Iterable, called tail.
static <A> Stream<A>	cons(Thunk<A> element) Creates a one-element new Stream that will retrieve the thunk's value.
static <A> Stream<A>	cons(Thunk<A> head, Stream<? extends A> tail) Creates a new Stream that retrieves elements from a head's thunk, and another Iterable, called tail.
static <A> Stream<A>	empty() Answers a Stream that has no elements.
static Stream<Integer>	enumerate(int start) Iterates from the starting integer, adding 1.
static Stream<Integer>	enumerate(int start, int stop) Iterates from the start integer, by adding 1, up to the stop integer, inclusive.
static Stream<Integer>	enumerate(int start, int stop, int step) Iterates from the start integer, by adding step, up to the stop integer, inclusive.
static <A> Stream<A>	from(A[] elements) Creates a new Stream that retrieves the elements from the given array.
static Stream<Character>	from(CharSequence charSequence) Creates a new Stream that retrieves character elements from the given charSequence
static <A> Stream<A>	from(Collection<? extends A> collection) Creates a new Stream that will retrieve elements from the given collection
static <A> Stream<A>	from(Deque<? extends A> list) Creates a new Stream that retrieves elements from a Deque.
static <A> Stream<A>	from(Enumeration<? extends A> enumeration) Creates a new Stream that retrieves elements from the given Enumeration.
static <A> Stream<A>	from(Iterable<? extends A> iterable) Create a new Stream that retrieves elements from the given Iterable.
static <A> Stream<A>	from(Iterator<? extends A> iterator) Creates a new Stream that retrieves elements from the given iterator.
static <A> Stream<A>	from(List<? extends A> list) Creates a new Stream that retrieves elements from a list.
static <A> Stream<A>	iterate(A seed, Applicable<? super A,? extends A> generator) Creates a new infinite Stream that retrieves element from the sequence where the nth element is the given function applied to the nth-1.
static <A> Stream<A>	iterateUntilNull(A seed, Applicable<? super A,? extends A> generator) Creates a new, potentially infinte Stream that iterates over the given seed and generator, but will stop before any retrieved element would be null.
static <A> Stream<A>	repeat(A element) Answers an infinite Stream that indefinitely retrieves the given element.
static <A> Stream<A>	repeat(Thunk<A> thunk) Answers an infinite Stream that indefinitely retrieves the given thunk's value.
static <A> Class<Stream<A>>	type() Answers the Stream class, but preserving its element generic type.
static <A> Stream<A>	undefined() Answers a one element Stream that throws an exception when trying to access its element.

Methods inherited from class java.lang.Object

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

Method Detail

cons

@Projection
@Conditionally(value=Repeatable.class)
public static <A> Stream<A> cons(Thunk<A> head,
                                                                               @NonNull
                                                                               Stream<? extends A> tail)

Creates a new Stream that retrieves elements from a head's thunk, and another Iterable, called tail. This operation is known and cons(tructing), and can be undone by sending Stream.delayedDecons() to the resulting Stream. The returned stream is Repeatable as long as the thunk's head value is always equal, and the tail is repeatable.

Type Parameters:

A -

Parameters:

head -

tail -

Returns:

a new Stream

cons

@Projection
@Conditionally(value=Repeatable.class)
public static <A> Stream<A> cons(A head,
                                                                               @NonNull
                                                                               Stream<? extends A> tail)

Creates a new Stream that retrieves elements from a head, and another Iterable, called tail. This operation is known and cons(tructing), and can be undone by sending Stream.decons() to the resulting Stream. * The returned stream is Repeatable as long as the tail is repeatable.

Type Parameters:

A -

Parameters:

head -

tail -

Returns:

a new Stream

cons

@Repeatable
@Projection
public static <A> Stream<A> cons(@NonNull
                                                       A... elements)

Creates a new Stream that retrieves the elements from the given array. This stream permits efficient random access and grants repeatable iteration order.

Type Parameters:

A - the element type

Parameters:

elements - the array that is Stream source

Returns:

a new stream that gets its elements from an array

cons

@Projection
@Repeatable
public static <A> Stream<A> cons(Thunk<A> element)

Creates a one-element new Stream that will retrieve the thunk's value. This stream is Repeatable as long as the thunk's value is always equal.

Type Parameters:

A -

Parameters:

element -

Returns:

a new

See Also:

Thunk.value()

cons

@Repeatable
@Projection
public static <A> Stream<A> cons(A element)

Creates a new Stream that will retrieve just the given element

Type Parameters:

A -

Parameters:

element - the single element the new Stream will retrieve

Returns:

a new Stream

iterate

@Projection
public static <A> Stream<A> iterate(@NonNull
                                               A seed,
                                               @NonNull
                                               Applicable<? super A,? extends A> generator)

Creates a new infinite Stream that retrieves element from the sequence where the nth element is the given function applied to the nth-1. If function is side-effect-free, the following sequence is generated:

 [seed, generator(seed), generator(generator(seed)), generator(generator(generator(seed))), ...]
 

Type Parameters:

A -

Parameters:

seed - the first value to be retrieved

generator - a function used to generated each element from the sequence after the initial element

Returns:

a new Stream that iterates over over the generated values

enumerate

@Projection
public static Stream<Integer> enumerate(int start)

Iterates from the starting integer, adding 1. This generates the infinite stream [start, start+1, start+2...]

Parameters:

start - the initial element of the sequence

Returns:

an stream that retrieves the sequence [start, start+1, start+2...]

Since:

1.2

enumerate

@Projection
public static Stream<Integer> enumerate(int start,
                                                   int stop)

Iterates from the start integer, by adding 1, up to the stop integer, inclusive. This generates the finite stream [start, start+1, start+2..., stop]

Parameters:

start - the initial element of the sequence

stop - the final element of the sequence

Returns:

an stream that retrieves the sequence [start, start+1, start+2..., stop]. As a particular case, if start == stop, the sequence [start] is retrieved. If start > stop, an empty stream is retrieved

Since:

1.2

enumerate

@Projection
public static Stream<Integer> enumerate(int start,
                                                   int stop,
                                                   int step)

Iterates from the start integer, by adding step, up to the stop integer, inclusive. This generates the finite stream [start, start+step, start+2*step..., stop]

Parameters:

start - the initial element of the sequence

stop - the final element of the sequence

step -

Returns:

an stream that retrieves the sequence [start, start+step, start+2*step..., stop]. As a particular case, if start == stop, the sequence [start] is retrieved. If start > stop, an empty stream is retrieved

Since:

1.2

iterateUntilNull

@Projection
public static <A> Stream<A> iterateUntilNull(@NonNull
                                                        A seed,
                                                        @NonNull
                                                        Applicable<? super A,? extends A> generator)

Creates a new, potentially infinte Stream that iterates over the given seed and generator, but will stop before any retrieved element would be null.

Type Parameters:

A -

Parameters:

seed - the first value to be retrieved

generator - a function used to generated each element from the sequence after the initial element

Returns:

a new Stream that iterates over over the generated values, until an element is null.

repeat

@Projection
public static <A> Stream<A> repeat(A element)

Answers an infinite Stream that indefinitely retrieves the given element.

Type Parameters:

A -

Parameters:

element -

Returns:

a new Stream that repeats the given element

repeat

@Projection
public static <A> Stream<A> repeat(@NonNull
                                              Thunk<A> thunk)

Answers an infinite Stream that indefinitely retrieves the given thunk's value.

Type Parameters:

A -

Parameters:

thunk - the Thunk whose value to repeat

Returns:

a new Stream

from

@Repeatable
@Projection
public static <A> Stream<A> from(@NonNull
                                                       A[] elements)

Creates a new Stream that retrieves the elements from the given array. Equivalent to cons(Object...)

Type Parameters:

A - the element type

Parameters:

elements - the array that is Stream source

Returns:

a new stream that gets its elements from an array

from

@Projection
@Conditionally(value=Repeatable.class)
public static <A> Stream<A> from(@NonNull
                                                                               Iterable<? extends A> iterable)

Create a new Stream that retrieves elements from the given Iterable.

Type Parameters:

A - the element type

Parameters:

iterable - the Iterable to decorate

Returns:

the given iterable, if it is Stream, a new stream that wraps it, otherwise

from

@Projection
public static <A> Stream<A> from(@NonNull
                                            Iterator<? extends A> iterator)

Creates a new Stream that retrieves elements from the given iterator. The resulting stream can not be iterated more than once, thus it is inherently mutable

Type Parameters:

A -

Parameters:

iterator - source of the the new Stream

Returns:

a new Stream

from

@Projection
public static <A> Stream<A> from(@NonNull
                                            Enumeration<? extends A> enumeration)

Creates a new Stream that retrieves elements from the given Enumeration. The resulting stream can not be iterated more than once, thus it is inherently mutable

Type Parameters:

A -

Parameters:

enumeration - source of the new Stream

Returns:

a new Stream

from

@Repeatable
@Projection
public static Stream<Character> from(@NonNull
                                                           CharSequence charSequence)

Creates a new Stream that retrieves character elements from the given charSequence

Parameters:

charSequence - source of the of characters of the new Stream

Returns:

a new Stream

from

@Repeatable
@Projection
public static <A> Stream<A> from(@NonNull
                                                       Collection<? extends A> collection)

Creates a new Stream that will retrieve elements from the given collection

Type Parameters:

A -

Parameters:

collection - source of the new Stream

Returns:

a new Stream

from

@Repeatable
@Projection
public static <A> Stream<A> from(@NonNull
                                                       List<? extends A> list)

Creates a new Stream that retrieves elements from a list. This streams grants repeatable iterator order and supports (not necessary efficient) random access by index.

Type Parameters:

A - the element type

Parameters:

list - the source of the new Stream

Returns:

a new Stream

from

@NonNull
@Repeatable
@Projection
public static <A> Stream<A> from(@NonNull
                                                               Deque<? extends A> list)

Creates a new Stream that retrieves elements from a Deque. This streams grants repeatable iterator order and supports (not necessary efficient) random access by index. This stream can be lazily reversed.

Type Parameters:

A - the element type

Parameters:

list - the source of the new Stream

Returns:

a new Stream

empty

@Constant
@Repeatable
public static <A> Stream<A> empty()

Answers a Stream that has no elements. This stream is immutable and singleton

Type Parameters:

A - the element type

Returns:

a singleton empty Stream

undefined

@Constant
public static <A> Stream<A> undefined()

Answers a one element Stream that throws an exception when trying to access its element.

Type Parameters:

A -

Returns:

a single elemtn Stream that throws an exception when accessing its only element

type

@Constant
public static <A> Class<Stream<A>> type()

Answers the Stream class, but preserving its element generic type. This method is mostly aimed to be used with Staccato-Commons-Lambda:

 lambda($(Streams.<User> type()).toList())
 

Type Parameters:

A -

Returns:

(Class<Stream<A>>) Stream.class