Stream (Staccatissimo-Collections 2.2 API)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.sf.staccatocommons.collections.stream
Interface Stream<A>


Type Parameters:: A - the type of object the stream is source of

All Superinterfaces:: ContainsAware<A>, EmptyAware, Iterable<A>, ProtoMonad<Stream<A>,Stream,A>, SizeAware

All Known Implementing Classes:: AbstractBasicStream, AbstractStream

public interface Stream<A>
extends ContainsAware<A>, Iterable<A>, ProtoMonad<Stream<A>,Stream,A>, SizeAware
extends ContainsAware<A>, Iterable<A>, ProtoMonad<Stream<A>,Stream,A>, SizeAware

A Stream is a lazy, rich-interfaced, Iterable, chained functional-style object that can retrieve and process an arbitrary - and potentially unbound - amount of other objects of a parameterized type. Such objects are called elements, and are generated by another object, called source. Some examples of elements and its source are:

Elements in a collection
Files in a directory
Characters in a string
Lines in a file
Rows in a result set
Virtually anything that has sense to iterate through

Streams have the following properties:

Operation oriented: A stream represents a single and eventually complex transformation over a source of objects; it is not a container
Reference Semantics: A stream internal state is meaningless, and Streams do not override Object's #equals(Object), #hashCode() nor #toString()
Non persistent: Streams are not Serializable Thus, they should not be used as attributes of long-living objects.
One-Message: Given a stream instance, only one message can be sent to it, sending more than one message to it has an undefined result, as a consequence, it may be iterated only once. There are three exceptions to this rule, though:
1. Methods inherited from Object like #toString() and #hashCode(). None of those methods affect the transformation nor the underlying source
2. SizeAware.isEmpty(): it may be sent multiple times and grants consistent results as long as no other message except of those at previous item is sent. This message does not affect the transformation, but may modify the underlying source
3. Streams returned by class or instance methods annotated with Repeatable, like force() or Streams.cons(Object). Such streams may be reused and receive any message any number of times, and grant consistent results, including repeatable iteration order.
Lazy projections: all of the - many - transformations exposed by streams that are annotated as Projection are lazy. Such methods do also work with very large o potentially infinte streams. Methods not annotated that way will not work on infinite streams, as they will never end normally

Streams provide messages for performing random access, however they do not warrant to implement them in an efficient manner, and it normally depends on the underlying source. Concrete, simple streams, collection handling-oriented, may be instantiated through Streams class. Other concrete streams are be provided by other staccato-commons libraries. Aside from these concrete streams, client code may also implement new ones. In order to do that, it must not implement this interface directly, but inherit from AbstractStream, which implements all methods except of iterator()

Author:: fbulgarelli

Nested Class Summary
`static interface`	`Stream.DeconsApplicable<A,B>` An `Applicable2` that can transform a `Stream` by deconstructing it into head and tail, or into an empty stream.
`static interface`	`Stream.DelayedDeconsApplicable<A,B>` An `Applicable2` that can transform a `Stream` by deconstructing it into head thunk and tail, or into an empty stream.
`static interface`	`Stream.EmptyApplicable<A>`

Method Summary

boolean all(Evaluable<? super A> predicate)
Tests if all elements satisfy the given Evaluable

boolean allEquiv()
Tests if all elements are equal

boolean allEquivBy(Evaluable2<? super A,? super A> equivTest)
Tests if all elements are equivalent, using the given equivTest

A any()
Returns the head() of this Stream The different between head() and any() is strictly semantic: use this message instead of head() whenever the code needs an unspecified element, rather than the first element of the stream.

boolean any(Evaluable<? super A> predicate)
Tests if at least one element satisfies the given Evaluable

A anyOrElse(A value)
Shorthand for anyOrNone().valueOrElse(value)

A anyOrElse(Thunk<A> thunk)
Shorthand for anyOrNone().valueOrElse(thunk)

Option<A> anyOrNone()
Returns the head() of the given Stream, just like any(), but as an option.

A anyOrNull()
Shorthand for anyOrNone().valueOrNull()

Stream<A> append(A element)
Adds an element as the last one of the stream.

Stream<A> append(Iterable<A> other)
Deprecated. use concat(Iterable) instead

Stream<A> append(Thunk<A> thunk)
Deprecated. use delayedAppend(Thunk) instead

Stream<A> appendUndefined()
Concatenates this Stream with the undefined Stream.

A average(NumberType<A> numberType)
Answers the average of the stream elements, using the given NumberType for performing addition and division.





<B,C> Stream<Tuple2<B,C>>

branch(Applicable<? super A,? extends B> function0,
       Applicable<? super A,? extends C> function1)

Answers a Stream of pairs, where each one contains both results of applying the given functions.





<B> Stream<Tuple2<A,B>>

clone(Applicable<? super A,? extends B> function)
Answers a stream that retrieves a tuple per each element, formed by the original element as the first component, and the result of applying the given function to it as the second component.

Stream<A> concat(A... elements)
Concatenates this with the given elements It answers an Stream that retrieves elements from this Stream, and then, after its last element, the given elements.

Stream<A> concat(Iterable<? extends A> other)
Concatenates this with other It answers an Stream that retrieves elements from this Stream, and then, after its last element, from the given iterable.

Stream<A> concat(Iterator<? extends A> other)
Concatenates this with the given Iterator It answers an Stream that retrieves elements from this Stream, and then, after its last element, the given iterator's elements.

boolean containsBefore(A element, A reference)
Answers if element is contained by this stream, and its first occurence is before the first occurence of the second one, if any.

boolean containsBeforeIndex(A element, int index)
Answers if element is contained by this stream, and its first occurence is before the given index.

int countOf(Evaluable<? super A> predicate)
Answers the number of element that satisfy the given predicate

Stream<Tuple2<A,A>> cross()
Answers the Cartesian product of this stream and itself





<B> Stream<Tuple2<A,B>>

cross(B... elements)
Answers the cartesian product of this Stream and the given elements.





<B> Stream<Tuple2<A,B>>

cross(Iterable other)
Answers the cartesian product of this Stream and the given Iterable





<B> Stream<Tuple2<A,B>>

cross(Iterator other)
Answers the cartesian product of this Stream and the given Iterator





<B> Stream<Tuple2<A,B>>

cross(Stream other)
Answers the Cartesian product of this stream and the given one

Stream<Stream<A>> crossStreams(Stream<Stream<A>> streamOfStreams)
Answers the cartesian product of this Stream and each one of the given streamOfStreams

Tuple2<A,Stream<A>> decons()
Answers this stream split into head and tail.

Stream<A> delayedAppend(Thunk<A> thunk)
Adds an element's thunk as the last one of the stream.

Tuple2<Thunk<A>,Stream<A>> delayedDecons()
Answers this non-empty stream split into a head thunk and tail.

Stream<A> delayedPrepend(Thunk<A> thunk)
Adds an element's thunk as the first one of the stream.

Stream<A> drop(int amountOfElements)
Discards up to N elements from this Stream.

Stream<A> dropWhile(Evaluable<? super A> predicate)
Discards all elements while they satisfy the given predicate

Stream<A> each(Executable<? super A> block)
Maps the given side effect over this stream, by answering a Stream that lazily applies the given side effect over each stream elements, and retrieves them.

boolean equiv(A... elements)
Test that the elements of this stream are equal to the elements of the given array, and in the same order.

boolean equiv(Iterable<? extends A> other)
Test that the elements of this stream are equal to the elements of the given Iterable, and in the same order.

boolean equiv(Iterator<? extends A> other)
Test that the elements of this stream are equal to the elements of the given iterator, and in the same order.

boolean equivBy(Evaluable2<? super A,? super A> equalityTest, A... elements)
Test that the elements of this stream are equivalent to the given elements, and in the same order, using the given equalityTest for determining equivalence between elements.

boolean equivBy(Evaluable2<? super A,? super A> equalityTest, Iterable<? extends A> iterable)
Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the given equalityTest for determining equivalence between elements.

boolean equivBy(Evaluable2<? super A,? super A> equalityTest, Iterator<? extends A> other)
Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the given equalityTest for determining equivalence between elements.





<B> boolean

equivOn(Applicable<? super A,? extends B> function,
        A... elements)

Test that the elements of this stream are equivalent to the given elements, and in the same order, using the Equiv.on(function) for determining equivalence between elements.





<B> boolean

equivOn(Applicable<? super A,? extends B> function,
        Iterable<? extends A> iterable)

Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the Equiv.on(function) for determining equivalence between elements.





<B> boolean

equivOn(Applicable<? super A,? extends B> function,
        Iterator<? extends A> other)

Test that the elements of this stream are equivalent to the elements of the given Iterator, and in the same order, using the Equiv.on(function) for determining equivalence between elements.

Stream<A>

filter(Evaluable<? super A> predicate)
Preserves elements that satisfy the given predicate

Example: //Answers stream [hello, world], which has only strings whose length is 5 Streams.cons("a", "hello", "world", "of", "streams", "!").

Stream<A> filterIndex(Evaluable<Integer> predicate)
Preserves elements that whose index satisfy the given predicate

A find(Evaluable<? super A> predicate)
Looks for a element that satisfies the given Evaluable.

int findIndex(Evaluable<? super A> predicate)
Answers the zero-based index of first element that matches the given predicate

A findOrElse(Evaluable<? super A> predicate, A element)
Looks for an element that satisfies the given Evaluable.

A findOrElse(Evaluable<? super A> predicate, Thunk<? extends A> thunk)
Looks for an element that satisfies the given Evaluable.

Option<A> findOrNone(Evaluable<? super A> predicate)
Looks for an element that satisfies the given Evaluable.

A findOrNull(Evaluable<? super A> predicate)
Looks for an element that satisfies the given Evaluable.

int findPosition(Evaluable<? super A> predicate)
Answers the zero-based index of first, present element that matches the given predicate.

A first()
Answers the first element.





<B> Stream<B>

flatMap(Function<? super A,? extends Iterable<? extends B>> function)
Transformes each element into an iterable using the given function, and concatenates (flattens) the result





<B> Stream<B>

flatMapArray(Function<? super A,? extends B[]> function)
Transformes each element into an array using the given function, and concatenates (flattens) the result





<B> B

fold(B initial,
     Applicable2<? super B,? super A,? extends B> function)

(Left)folds this Stream using an initial value and the given two-arg function, producing a single aggregated result from all the Stream elements.

Stream<A> force()
Forces stream elements evaluation by converting it into a new ordered stream one that is not lazy and that has repeatable iteration order.

void forEach(Executable<? super A> block)
Executes the given Executable block for each element.

A get(int n)
Answers the n-th element.





<K,V> Map<K,V>

groupOn(Applicable<? super A,K> groupFunction,
        Reduction<A,V> reduction)

Groups elements by the given groupingFunction, and reduces each group using the given reduction.

A head()
Answers the head of the Stream, which is the first element of the stream.

Stream<A> incorporate(A element)
Inserts the given value after each element of the stream.

Stream<A> incorporate(Function<? super A,? extends A> function)
Inserts after each element the result of applying the given function to it.

int indexOf(A element)
Answers the zero-based index of the given element

Stream<Integer> indices(Evaluable<? super A> predicate)
Answers a stream containing all the zero-based indices of the elements that matches the given predicate

Stream<A> insertBefore(A element, A reference)
Inserts element before the first occurrence of reference.

Stream<A> insertBeforeIndex(A element, int index)
Inserts element at index - 1.

Stream<A> intersperse(A element)
Inserts the given element between each retrieved element of this Stream

boolean isBefore(A previous, A next)
Answers if both arguments are contained by this stream, and the first one is before the second one.

Thriterator<A> iterator()

String joinStrings(String separator)
(Left)folds this Stream concatenating each elements toString with a separator

A last()
Answers the last element of this stream.





<B> Stream<B>

map(Applicable<? super A,? extends B> function)
Transforms each element using the given function





<B> Stream<B>

map(Function<? super A,? extends B> function)
Transforms each element using the given function.

A maximum()
Answers the maximum element of the stream, using elements natural order.

A maximumBy(Comparator<? super A> comparator)
Answers the maximum element of the stream, using the given comparator to compare elements.





<B extends Comparable<B>> 


A

maximumOn(Applicable<? super A,B> function)
Answers the maximum element of the stream, using the given Compare.on(function) to compare elements.

Stream<A> memoize()
Memoizes stream elements and their order, by answering a lazy stream with Repeatable iteration order that caches elements evaluated during iteration.

Stream<A> memorize()
Deprecated. the exact name of this concept is memoization, not memorization. Use memoize() instead

A minimum()
Answers the minimum element of the stream, using elements natural order.

A minimumBy(Comparator<? super A> comparator)
Answers the min element of the stream, using the given comparator to compare elements.





<B extends Comparable<B>> 


A

minimumOn(Applicable<? super A,B> function)
Answers the minimum element of the stream, using the given Compare.on(function) to compare elements.

Tuple2<List<A>,List<A>> partition(Evaluable<? super A> predicate)
Splits stream elements into two lists using a predicate - elements that evaluate to true will be returned in the first component, the rest will be returned in the second component

int positionOf(A element)
Answers the index of the given present element.

Stream<A> prepend(A element)
Adds an element as the first one of the stream.

Stream<A> prepend(Thunk<A> thunk)
Deprecated. use delayedPrepend(Thunk)

void print()
Prints the stream elements to System.out

void print(Appendable destination)
Prints the stream elements to an appendable, like StringBuilder or a Writer

void println()
Prints the stream elements to System.out, followed by a newline character.

void println(Appendable o)
Prints the stream elements to an appendable, like StringBuilder or a Writer, followed by a newline character

String printString()
Prints the stream elements to a string

A product(NumberType<A> numberType)
Answers the product of the elements of this Stream using the given NumberType

A reduce(Applicable2<? super A,? super A,? extends A> function)
(Left)folds the tail of this Stream using the first element of the stream as initial value, producing a single aggregated result from all the Stream elements.





<B> B

reduce(Reduction<? super A,B> reduction)
Answers the result of aggregating this stream using the given reduction

Stream<A> reverse()
Reverses this Stream, by returning a new Stream that retrieves elements in the inverse order of this Stream.

A second()
Answers the second element.

Stream<A> skip(A element)
Preserves all elements but those that are equal to the given one.

Stream<A> skipIndex(int index)
Answers a streams that retrieves all the elements of this one, except of that at the given index

Stream<A> slice(int beginIndex, int endIndex)
Answers a stream that is a substream of this one.

Stream<A> sort()
Sorts this Stream, using their element's natural ordering

Stream<A> sortBy(Comparator<A> comparator)
Sorts this Stream, using the given comparator





<B extends Comparable<B>> 


Stream<A>

sortOn(Applicable<? super A,B> function)
Sorts this Stream, using Compare.on(function) as comparator

Tuple2<Stream<A>,Stream<A>> streamPartition(Evaluable<? super A> predicate)
Splits stream elements into two ordered streams, that support random access.

A sum(NumberType<A> numberType)
Answers the sum of the elements of this Stream using the given NumberType

Stream<A> tail()
Answers the tail of the Stream

Stream<A> take(int amountOfElements)
Preserves up to N elements.

Stream<A> takeWhile(Evaluable<? super A> predicate)
Preserves all elements while they satisfy the given predicate

A third()
Answers the third element.

A[] toArray(Class<? super A> clazz)
Creates a new array that has the same elements that the retrived by this Stream

List<A> toList()
* Converts this Stream into a List, by adding all its elements to a new List.

Set<A> toSet()
Converts this Stream into a Set, by adding all its elements to a new Set.





<B> Stream<B>

transform(Applicable<Stream<A>,? extends Stream> function)
Lazily applies the given function to this Stream.





<B> Stream<B>

transform(Stream.DeconsApplicable<A,B> function)
Lazily applies the given function to this stream, deconstructing this stream into head and tail, or into an empty stream.





<B> Stream<B>

transform(Stream.DelayedDeconsApplicable<A,B> function)
Lazily applies the given function to this stream, deconstructing this stream into a head thunk and tail, or into an empty stream.





<B> Stream<Tuple2<A,B>>

zip(B... elements)
Returns a Stream formed by by pair of element from this and the given elements.





<B> Stream<Tuple2<A,B>>

zip(Iterable iterable)
Returns a Stream formed by by pair of element from this and the given iterable.





<B,C> Stream<C>

zip(Iterable<B> iterable,
    Function2<? super A,? super B,C> function)

Deprecated. use zipWith(Function2, Iterable)





<B> Stream<Tuple2<A,B>>

zip(Iterator other)
Returns a Stream formed by by pair of element from this and the given Iterator.





<B,C> Stream<C>

zipWith(Function2<? super A,? super B,C> function,
        B... elements)

Returns a Stream formed by the result of applying the given function to each pair of elements from this and the given iterable.





<B,C> Stream<C>

zipWith(Function2<? super A,? super B,C> function,
        Iterable<B> other)

Returns a Stream formed by the result of applying the given function to each pair of elements from this and the given iterable.





<B,C> Stream<C>

zipWith(Function2<? super A,? super B,C> function,
        Iterator<B> other)

Returns a Stream formed by the result of applying the given function to each pair of elements from this and the other.

Methods inherited from interface net.sf.staccatocommons.defs.partial.ContainsAware
`contains`

Methods inherited from interface net.sf.staccatocommons.defs.ProtoMonad
`replace, replaceNull, skipNull`

Methods inherited from interface net.sf.staccatocommons.defs.partial.SizeAware
`isEmpty, size`

Method Detail

iterator

Thriterator<A> iterator()

Specified by:: iterator in interface Iterable<A>

forEach

void forEach(@NonNull
             Executable<? super A> block)

Executes the given Executable block for each element. This message is equivalent to a for-each loop over this Stream

Specified by:: forEach in interface ProtoMonad<Stream<A>,Stream,A>

Parameters:: block -
Since:: 1.2

each

@Projection
Stream<A> each(@NonNull
                          Executable<? super A> block)

Maps the given side effect over this stream, by answering a Stream that lazily applies the given side effect over each stream elements, and retrieves them.

Specified by:: each in interface ProtoMonad<Stream<A>,Stream,A>

Parameters:: block -
Returns:: map(Functions.impure(block)
Since:: 1.1 original version, replaced by forEach(Executable), 1.2 current version, incompatible with previous 1.1

map

@Projection
<B> Stream<B> map(@NonNull
                             Applicable<? super A,? extends B> function)

Transforms each element using the given function

Specified by:: map in interface ProtoMonad<Stream<A>,Stream,A>

Type Parameters:: B -
Parameters:: function - the mapper used to transform each element, applying it
Returns:: a new Stream projection that will retrieve the result of applying the given function to each element

filter

@Projection
Stream<A> filter(@NonNull
                            Evaluable<? super A> predicate)

Preserves elements that satisfy the given predicate

Example:

  //Answers stream [hello, world], which has only strings whose length is 5   
  Streams.cons("a", "hello", "world", "of", "streams", "!").filter(length().equal(5));

Specified by:: filter in interface ProtoMonad<Stream<A>,Stream,A>

Parameters:: predicate -
Returns:: a new Stream projection that will retrieve only elements that evaluate to true

skip

@Projection
Stream<A> skip(@NonNull
                          A element)

Preserves all elements but those that are equal to the given one. Equivalent to filter(Predicates.equal(element).not())

Specified by:: skip in interface ProtoMonad<Stream<A>,Stream,A>

Parameters:: element -
Returns:: a Stream that retrieves all elements that are not equal to the given one

takeWhile

@Projection
Stream<A> takeWhile(@NonNull
                               Evaluable<? super A> predicate)

Preserves all elements while they satisfy the given predicate

Parameters:: predicate -
Returns:: a new Stream projection that will retrieve all elements from this stream, as long as none of them evaluates to false.

take

@Projection
Stream<A> take(@NotNegative
                          int amountOfElements)

Preserves up to N elements. It this Stream size is shorter than the given amountOfElements, the resulting stream will retrieve the same elements than this stream.

Parameters:: amountOfElements -
Returns:: a new Stream projection that will retrieve up to N elements

dropWhile

@Projection
Stream<A> dropWhile(@NonNull
                               Evaluable<? super A> predicate)

Discards all elements while they satisfy the given predicate

Parameters:: predicate -
Returns:: a new Stream projection that will skip all elements as long as they satisfy the given Evaluable

drop

@Projection
Stream<A> drop(@NotNegative
                          int amountOfElements)

Discards up to N elements from this Stream. Is the Stream size is shorter than the given amountOfElements, the resulting stream will be empty.

Parameters:: amountOfElements - the amount of elements to discard
Returns:: a new Stream that discards up to the given amountOfElements

slice

@Projection
Stream<A> slice(@NotNegative
                           int beginIndex,
                           @NotNegative
                           int endIndex)

Answers a stream that is a substream of this one. The substream begins at the specified beginIndex, and extends to the element at index endIndex - 1, if it has enough elements, or up to its last element, otherwise.

The resulting stream is always finite, and satisfies that size() <= endIndex - beginIndex

As a particular case, if beginIndex == endIndex, an empty stream is returned.

Examples:

  Streams.from("hamburger").slice(4, 8).joinStrings(""); //answers "urge"
  Streams.from("smiles").slice(1, 5).joinStrings(""); //answers "mile"
  Streams.from("hello world!").slice(6, 309).joinStrings(""); //answers "world!"
  Streams.enumerate(1,20).slice(5,5).toList(); //answers []

Parameters:: beginIndex - the lower bound, inclusive; endIndex - the upper bound, exclusive
Returns:: drop(beginIndex).take(endIndex - beginIndex)

partition

@NonNull
Tuple2<List<A>,List<A>> partition(@NonNull
                                          Evaluable<? super A> predicate)

Splits stream elements into two lists using a predicate - elements that evaluate to true will be returned in the first component, the rest will be returned in the second component

Parameters:: predicate -
Returns:: a new Tuple2 that contains this stream partitioned into two lists.

streamPartition

@NonNull
Tuple2<Stream<A>,Stream<A>> streamPartition(@NonNull
                                                    Evaluable<? super A> predicate)

Splits stream elements into two ordered streams, that support random access. This method just converts list returned by partition(Evaluable) into Streams.

Parameters:: predicate -
Returns:: a new Tuple2 that contains this stream partitioned into two other streams.

map

@Projection
<B> Stream<B> map(@NonNull
                             Function<? super A,? extends B> function)

Transforms each element using the given function.

Example:

 
  import static import net.sf.staccatocommons.util.Strings.*;
  //Answers [HELLO, WORLD, STREAMS]
  Streams.cons("hello", "world", "streams").map(toUpperCase());

 import static net.sf.staccatocommons.numbers.NumberTypes.*;
  ...
 //answers Stream [6, 9, 11, 26]
 Streams.cons(5, 8, 10, 25).map(add(1)).println();

Type Parameters:: B -
Parameters:: function - the mapper used to transform each element, applying it
Returns:: a new Stream projection that will retrieve the result of applying the given function to each element

flatMap

@Projection
<B> Stream<B> flatMap(@NonNull
                                 Function<? super A,? extends Iterable<? extends B>> function)

Transformes each element into an iterable using the given function, and concatenates (flattens) the result

Type Parameters:: B -
Parameters:: function -
Returns:: a new Stream that will retrieve the result of transforming each element and concatenating those transformations

flatMapArray

@Projection
<B> Stream<B> flatMapArray(@NonNull
                                      Function<? super A,? extends B[]> function)

Transformes each element into an array using the given function, and concatenates (flattens) the result

Type Parameters:: B -
Parameters:: function -
Returns:: a new Stream that will retrieve the result of transforming each element and concatenating those trsansformations

reverse

@NonNull
Stream<A> reverse()

Reverses this Stream, by returning a new Stream that retrieves elements in the inverse order of this Stream. This may not be a Projection, depending on if the stream's source permits it.

Returns:: a new Stream that retrieves elements in the inverse order of this stream.

any

A any()
      throws EmptySourceException

Returns the head() of this Stream The different between head() and any() is strictly semantic: use this message instead of head() whenever the code needs an unspecified element, rather than the first element of the stream.

Returns:: head()
Throws:: EmptySourceException - if this Stream has no elements.

anyOrNone

@NonNull
Option<A> anyOrNone()

Returns the head() of the given Stream, just like any(), but as an option. If Stream has no elements, instead of throwing a EmptySourceException, it returns None

Returns:: Option.some(element) if there is at least one element, or Option.none(), otherwise.

anyOrNull

A anyOrNull()

Shorthand for anyOrNone().valueOrNull()

Returns:: anyOrNone().valueOrNull()

anyOrElse

A anyOrElse(@NonNull
            Thunk<A> thunk)

Shorthand for anyOrNone().valueOrElse(thunk)

Parameters:: thunk -
Returns:: anyOrNone().valueOrElse(thunk)

anyOrElse

A anyOrElse(A value)

Shorthand for anyOrNone().valueOrElse(value)

Parameters:: value -
Returns:: anyOrNone().valueOrElse(value)

find

A find(@NonNull
       Evaluable<? super A> predicate)
       throws EmptySourceException,
              NoSuchElementException

Looks for a element that satisfies the given Evaluable. If such element does not exist, throws NoSuchElementException

Parameters:: predicate -
Returns:: the first elements that the predicate satisfies, if exists.
Throws:: EmptySourceException - if this stream is empty; NoSuchElementException - if no element matches the predicate.

findOrNone

@NonNull
Option<A> findOrNone(@NonNull
                             Evaluable<? super A> predicate)

Looks for an element that satisfies the given Evaluable. If such element exists, returns some(element). Otherwise, returns None.

Parameters:: predicate -
Returns:: None if no element matches the predicate, or some(element) if at least one exists. As a particular case, this method will return None if Stream is empty, regardless of the given predicate

findOrNull

A findOrNull(@NonNull
             Evaluable<? super A> predicate)

Looks for an element that satisfies the given Evaluable. If such element exists, returns it. Otherwise, returns null.

Parameters:: predicate -
Returns:: null if no element matches the predicate, or an element that satisfies it, if at least one exists. As a particular case, this method will return null if Stream is empty, regardless of the given predicate

findOrElse

A findOrElse(@NonNull
             Evaluable<? super A> predicate,
             @NonNull
             Thunk<? extends A> thunk)

Looks for an element that satisfies the given Evaluable. If such element exists, returns it. Otherwise, returns the given thunk's value.

Parameters:: predicate -
Returns:: thunk.value() if no element matches the predicate, or an element that satisfies it, if at least one exists. As a particular case, this method will return the thunk's value if Stream is empty, regardless of the given predicate

findOrElse

A findOrElse(@NonNull
             Evaluable<? super A> predicate,
             @NonNull
             A element)

Looks for an element that satisfies the given Evaluable. If such element exists, returns it. Otherwise, returns the given element .

Parameters:: predicate -
Returns:: findOrElse(predicate, Thunks.constant(element))

all

boolean all(@NonNull
            Evaluable<? super A> predicate)

Tests if all elements satisfy the given Evaluable

Parameters:: predicate - an Evaluable to evaluate each element
Returns:: if all the elements evaluate to true

allEquiv

boolean allEquiv()

Tests if all elements are equal

Returns:: if all the elements are equal

allEquivBy

boolean allEquivBy(Evaluable2<? super A,? super A> equivTest)

Tests if all elements are equivalent, using the given equivTest

Parameters:: equivTest - an Evaluable2 used to testing if an element is equivalent to another
Returns:: if all the elements are equal

any

boolean any(@NonNull
            Evaluable<? super A> predicate)

Tests if at least one element satisfies the given Evaluable

Parameters:: predicate - an Evaluable to evaluate each element
Returns:: if any element evaluate to true

equiv

boolean equiv(A... elements)

Test that the elements of this stream are equal to the elements of the given array, and in the same order.

Parameters:: elements -
Returns:: true if this stream has the same number of elements that the given array, and each pair formed by elements of this stream and the given array at same position are equal. false otherwise

equiv

boolean equiv(Iterable<? extends A> other)

Test that the elements of this stream are equal to the elements of the given Iterable, and in the same order.

Parameters:: other -
Returns:: true if this stream has the same number of elements that other, and each pair formed by elements of this stream and given iterable at same position are equal. false otherwise

equiv

boolean equiv(Iterator<? extends A> other)

Test that the elements of this stream are equal to the elements of the given iterator, and in the same order.

Parameters:: iterable -
Returns:: true if this stream has the same number of elements that other, and each pair formed by elements of this stream and given iterable at same position are equal. false otherwise
Since:: 2.2

equivBy

boolean equivBy(@NonNull
                Evaluable2<? super A,? super A> equalityTest,
                @NonNull
                Iterable<? extends A> iterable)

Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the given equalityTest for determining equivalence between elements.

Parameters:: equalityTest -; iterable -
Returns:: true if this stream has the same number of elements that the given iterable, and each pair formed by elements of this stream and given iterable at same position satisfies the given Evaluable2

equivBy

boolean equivBy(@NonNull
                Evaluable2<? super A,? super A> equalityTest,
                @NonNull
                Iterator<? extends A> other)

Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the given equalityTest for determining equivalence between elements.

Parameters:: equalityTest -; iterable -
Returns:: true if this stream has the same number of elements that other, and each pair formed by elements of this stream and other at same position satisfies the given Evaluable2
Since:: 2.2

equivBy

boolean equivBy(@NonNull
                Evaluable2<? super A,? super A> equalityTest,
                A... elements)

Test that the elements of this stream are equivalent to the given elements, and in the same order, using the given equalityTest for determining equivalence between elements.

Parameters:: equalityTest -; iterable -
Returns:: true if this stream has the same number of elements that the given elements, and each pair formed by elements of this stream and given elements at same position satisfies the given Evaluable2

equivOn

<B> boolean equivOn(@NonNull
                    Applicable<? super A,? extends B> function,
                    @NonNull
                    Iterable<? extends A> iterable)

Test that the elements of this stream are equivalent to the elements of the given Iterable, and in the same order, using the Equiv.on(function) for determining equivalence between elements.

Parameters:: function -; iterable -
Returns:: true if this stream has the same number of elements that the given iterable, and each pair formed by elements of this stream and given iterable at same position satisfies the Evaluable2 Equiv.on(function)

equivOn

<B> boolean equivOn(@NonNull
                    Applicable<? super A,? extends B> function,
                    @NonNull
                    Iterator<? extends A> other)

Test that the elements of this stream are equivalent to the elements of the given Iterator, and in the same order, using the Equiv.on(function) for determining equivalence between elements.

Parameters:: function -; iterable -
Returns:: true if this stream has the same number of elements that the given Iterator, and each pair formed by elements of this stream and given Iterator at same position satisfies the Evaluable2 Equiv.on(function)
Since:: 2.2

equivOn

<B> boolean equivOn(@NonNull
                    Applicable<? super A,? extends B> function,
                    A... elements)

Test that the elements of this stream are equivalent to the given elements, and in the same order, using the Equiv.on(function) for determining equivalence between elements.

Parameters:: function -; iterable -
Returns:: true if this stream has the same number of elements that the given elements, and each pair formed by elements of this stream and the given elements at same position satisfies the Evaluable2 Equiv.on(function)

fold

<B> B fold(B initial,
           @NonNull
           Applicable2<? super B,? super A,? extends B> function)

(Left)folds this Stream using an initial value and the given two-arg function, producing a single aggregated result from all the Stream elements. This consist of taking the initial value and a Stream element, applying the function to them, and then repeating the process with this result as the next initial value and the next element from the stream. The last returned value is the folding result.

Type Parameters:: B -
Parameters:: initial -; function -
Returns:: the aggregates result
See Also:: Folds

reduce

A reduce(@NonNull
         Applicable2<? super A,? super A,? extends A> function)
         throws EmptySourceException

(Left)folds the tail of this Stream using the first element of the stream as initial value, producing a single aggregated result from all the Stream elements.

Parameters:: function -
Returns:: the folding result
Throws:: EmptySourceException - if this Stream is empty
See Also:: fold(Object, Applicable2), Folds

reduce

<B> B reduce(Reduction<? super A,B> reduction)
         throws NoSuchElementException

Answers the result of aggregating this stream using the given reduction

Parameters:: reduction -
Returns:: the folding result
Throws:: NoSuchElementException
Since:: 1.2

joinStrings

@NonNull
String joinStrings(@NonNull
                           String separator)

(Left)folds this Stream concatenating each elements toString with a separator

Parameters:: separator -
Returns:: the string representation of each element concatenated using a separator

sum

@NonNull
A sum(@NonNull
              NumberType<A> numberType)

Answers the sum of the elements of this Stream using the given NumberType

Parameters:: numberType -
Returns:: the result of adding each element, or zero, if this stream is empty
See Also:: Iterables.sum(Iterable, NumberType)

product

@NonNull
A product(@NonNull
                  NumberType<A> numberType)

Answers the product of the elements of this Stream using the given NumberType

Parameters:: numberType -
Returns:: the result of multiplying each element, or one, if this stream is empty
See Also:: Iterables.product(Iterable, NumberType)

average

A average(@NonNull
          NumberType<A> numberType)
          throws ArithmeticException

Answers the average of the stream elements, using the given NumberType for performing addition and division.

Parameters:: numberType -
Returns:: the average of the stream elements
Throws:: ArithmeticException - if the stream is empty and number type does not support zero division

countOf

int countOf(Evaluable<? super A> predicate)

Answers the number of element that satisfy the given predicate

Parameters:: predicate -
Returns:: filter(predicate).size()
Since:: 2.1

sort

@Projection
Stream<A> sort()

Sorts this Stream, using their element's natural ordering

Returns:: a new Stream

sortBy

@Projection
Stream<A> sortBy(@NonNull
                            Comparator<A> comparator)

Sorts this Stream, using the given comparator

Parameters:: comparator -
Returns:: a new Stream

sortOn

@Projection
<B extends Comparable<B>> Stream<A> sortOn(Applicable<? super A,B> function)

Sorts this Stream, using Compare.on(function) as comparator

Type Parameters:: B -
Parameters:: function -
Returns:: a new Stream

minimumBy

@NonNull
A minimumBy(@NonNull
                    Comparator<? super A> comparator)
            throws EmptySourceException

Answers the min element of the stream, using the given comparator to compare elements.

Parameters:: comparator -
Returns:: the minimum element.
Throws:: EmptySourceException - if the stream is empty.

minimumOn

<B extends Comparable<B>> A minimumOn(@NonNull
                                      Applicable<? super A,B> function)
            throws EmptySourceException

Answers the minimum element of the stream, using the given Compare.on(function) to compare elements.

Parameters:: function -
Returns:: the minimum element.
Throws:: EmptySourceException - if the stream is empty.

minimum

@NonNull
A minimum()
          throws ClassCastException,
                 EmptySourceException

Answers the minimum element of the stream, using elements natural order.

Returns:: the minimum element.
Throws:: EmptySourceException - if the stream is empty.; ClassCastException - if elements are not comparable

maximumBy

@NonNull
A maximumBy(@NonNull
                    Comparator<? super A> comparator)
            throws EmptySourceException

Answers the maximum element of the stream, using the given comparator to compare elements.

Parameters:: comparator -
Returns:: the maximum element.
Throws:: EmptySourceException - if the stream is empty.

maximumOn

<B extends Comparable<B>> A maximumOn(@NonNull
                                      Applicable<? super A,B> function)
            throws EmptySourceException

Answers the maximum element of the stream, using the given Compare.on(function) to compare elements.

Parameters:: function -
Returns:: the maximum element.
Throws:: EmptySourceException - if the stream is empty.

maximum

@NonNull
A maximum()
          throws ClassCastException,
                 EmptySourceException

Answers the maximum element of the stream, using elements natural order.

Returns:: the maximum element.
Throws:: EmptySourceException - if the stream is empty.; ClassCastException - if elements are not comparable

append

@Projection
Stream<A> append(@NonNull
                            Iterable<A> other)

Deprecated. use concat(Iterable) instead

Equivalent to concat(Iterable)

concat

@Projection
Stream<A> concat(@NonNull
                            Iterable<? extends A> other)

Concatenates this with other It answers an Stream that retrieves elements from this Stream, and then, after its last element, from the given iterable. As a particular case, if this Stream is infinite, the resulting Stream will retrieve the same elements than this one.

Parameters:: other -
Returns:: a new Stream
Since:: 2.2

concat

@Projection
Stream<A> concat(@NonNull
                            A... elements)

Concatenates this with the given elements It answers an Stream that retrieves elements from this Stream, and then, after its last element, the given elements.

As a particular case, if this Stream is infinite, the resulting Stream will retrieve the same elements than this one.

Example:

 //answers the Stream [0, 1, 2, 3]
 Streams.cons(0, 1).concat(2, 3);

Parameters:: elements - the element to add at the end of the stream
Returns:: a new Stream
Since:: 2.2

concat

Stream<A> concat(@NonNull
                 Iterator<? extends A> other)

Concatenates this with the given Iterator It answers an Stream that retrieves elements from this Stream, and then, after its last element, the given iterator's elements. As a particular case, if this Stream is infinite, the resulting Stream will retrieve the same elements than this one.

Parameters:: other - the iterator whose elements will be added at the end of the stream
Returns:: a new Stream
Since:: 2.2

appendUndefined

@Projection
Stream<A> appendUndefined()

Concatenates this Stream with the undefined Stream. Equivalent to concat(Streams.undefined())

Returns:: a new Stream, Repeatable as long as this is repeatable
See Also:: Streams.undefined()

append

@Projection
Stream<A> append(A element)

Adds an element as the last one of the stream.

Parameters:: element -
Returns:: a new Stream that retrieves this Stream elements, and then, the given element

append

@Deprecated
@Projection
Stream<A> append(@NonNull
                                       Thunk<A> thunk)

Deprecated. use delayedAppend(Thunk) instead

Equivalent to delayedAppend(Thunk).

delayedAppend

@Projection
Stream<A> delayedAppend(@NonNull
                                   Thunk<A> thunk)

Adds an element's thunk as the last one of the stream.

Parameters:: thunk -
Returns:: a new Stream that retrieves this Stream elements, and then, the value of the given thunk
Since:: 2.2

prepend

@Projection
Stream<A> prepend(A element)

Adds an element as the first one of the stream.

Parameters:: element -
Returns:: a new Stream that retrieves the given element, and then, this Stream elements.

prepend

@Deprecated
@Projection
Stream<A> prepend(@NonNull
                                        Thunk<A> thunk)

Deprecated. use delayedPrepend(Thunk)

Equivalent to delayedPrepend(Thunk)

delayedPrepend

@Projection
Stream<A> delayedPrepend(@NonNull
                                    Thunk<A> thunk)

Adds an element's thunk as the first one of the stream.

Parameters:: thunk -
Returns:: a new Stream that retrieves the value of the given thunk, and then, this Stream elements.

insertBeforeIndex

Stream<A> insertBeforeIndex(A element,
                            @NotNegative
                            int index)

Inserts element at index - 1. If stream has not enough elements, that is, stream size is less than or equal to index elements, the element is inserted at its end.

This message ensures that for any finite stream, and any element and index

  stream.insertBeforeIndex(element, index).containsBeforeIndex(element, index + 1)

is true.

Examples:

  Streams.cons(4, 5, 6).insertBeforeIndex(0, 2); //answers [4, 5, 0, 6]
  Streams.repeat(1).take(4).insertBeforeIndex(0, 2); //answers [1, 1, 0, 1, 1]
  Streams.repeat(1).take(4).insertBeforeIndex(0, 20); //answers [1, 1, 1, 1, 0]

Parameters:: element - the element to insert; index - the index before inserting it
Returns:: a Stream that lazily inserts the given element before the given index
Since:: 2.2

insertBefore

@Projection
Stream<A> insertBefore(A element,
                                  A reference)

Inserts element before the first occurrence of reference. If reference is not contained by this stream, the element is inserted at its end.

This message ensures that for any finite stream, and any element and reference

  stream.insertBefore(element, ref).containsBefore(element, ref)

is true.

Examples:

  Streams.cons('a', 'b', 'c').insertBefore('x', 'a'); //answers [x,a,b,c]
  Streams.cons('a', 'b', 'c').insertBefore('x', 'c'); //answers [a,b,x,c]
  Streams.cons('a', 'b', 'c').insertBefore('x', 'd'); //answers [a,b,c,x]

Parameters:: element -; reference -
Returns:: a Stream that lazily inserts the given element before the reference
Since:: 2.2

clone

@Projection
<B> Stream<Tuple2<A,B>> clone(Applicable<? super A,? extends B> function)

Answers a stream that retrieves a tuple per each element, formed by the original element as the first component, and the result of applying the given function to it as the second component.

This message is equivalent to map(Tuples.clone(function))

Parameters:: function - the function to apply to each element
Returns:: a new Stream
Since:: 1.2
See Also:: Tuples.clone(Applicable)

branch

@Projection
<B,C> Stream<Tuple2<B,C>> branch(Applicable<? super A,? extends B> function0,
                                            Applicable<? super A,? extends C> function1)

Answers a Stream of pairs, where each one contains both results of applying the given functions. Equivalent to this.map(Tuples.branch(function0, function1))

Type Parameters:: B -; C -
Parameters:: function0 -; function1 -
Returns:: a new Stream
Since:: 1.2
See Also:: Tuples.branch(Applicable, Applicable)

zipWith

@Projection
<B,C> Stream<C> zipWith(Function2<? super A,? super B,C> function,
                                   @NonNull
                                   B... elements)

Returns a Stream formed by the result of applying the given function to each pair of elements from this and the given iterable. If either this or the given iterable is shorter than the other given number of elements, the remaining elements of this are discarded

Example:

 //Answers the stream [1 + 4, 2 + 5] == [5, 7];
 Streams.cons(1, 2).zipWith(integer().add(), 4, 5);

Parameters:: elements - the elements to zip with this Stream; function - the function to apply to each pair
Returns:: a new Stream which is the result of applying the given Applicable2 to each pair this Stream and the elements. The resulting Stream size is the minimum of this size and the number of elements
See Also:: Iterables.zip(Iterable, Iterable)

zipWith

@Projection
<B,C> Stream<C> zipWith(Function2<? super A,? super B,C> function,
                                   @NonNull
                                   Iterable<B> other)

Type Parameters:: B - the type to the iterable to zip with this Stream; C - the resulting Stream element type
Parameters:: iterable - the Iterable to zip with this Stream; function - the function to apply to each pair
Returns:: a new Stream formed applying the given Applicable2 to each pair this Stream and the given iterable. The resulting Stream size is the minimum of both iterables sizes, or infinite, if both this and iterable are
See Also:: Iterables.zip(Iterable, Iterable)

zipWith

<B,C> Stream<C> zipWith(Function2<? super A,? super B,C> function,
                        @NonNull
                        Iterator<B> other)

Returns a Stream formed by the result of applying the given function to each pair of elements from this and the other. If either this or the given Iterator is shorter than the other one, the remaining elements are discarded.

Type Parameters:: B - the type to the iterable to zip with this Stream; C - the resulting Stream element type
Parameters:: other - the Iterator to zip with this Stream; function - the function to apply to each pair
Returns:: a new Stream formed applying the given Applicable2 to each pair this Stream and the given iterator. The resulting Stream size is the minimum of both iterables sizes, or infinite, if both this and other are
Since:: 2.2
See Also:: Iterables.zip(Iterable, Iterable)

zip

@Deprecated
@Projection
<B,C> Stream<C> zip(@NonNull
                                          Iterable<B> iterable,
                                          Function2<? super A,? super B,C> function)

Deprecated. use zipWith(Function2, Iterable)

Equivalent to zipWith(Function2, Iterable), with arguments interchanged

zip

@Projection
<B> Stream<Tuple2<A,B>> zip(@NonNull
                                       B... elements)

Returns a Stream formed by by pair of element from this and the given elements. If either this or the given array is shorter than the other one, the remaining elements are discarded.

Examples:

 //Answers the stream [(0, a), (1,b), (2,c)]
 Streams.cons(0, 1, 2).zip('a', 'b', 'c');

 //Answers true
 Streams 
   .from("hello")
   .zip(Streams.from("world!"))
   .equiv( 
     _('h', 'w'),
     _('e', 'o'),
     _('l', 'r'),
     _('l', 'l'),
     _('o', 'd')); //notice the last '!' was discarded

Type Parameters:: B -
Parameters:: iterable -
Returns:: a new Stream formed applying the given Applicable2 to each pair this Stream and the given elements. The resulting Stream size is the minimum of both iterables sizes.
Since:: 2.2
See Also:: zip(Iterable, Function2)

zip

@Projection
<B> Stream<Tuple2<A,B>> zip(@NonNull
                                       Iterable<B> iterable)

Returns a Stream formed by by pair of element from this and the given iterable. If either this or the given iterable is shorter than the other one, the remaining elements are discarded.

Type Parameters:: B -
Parameters:: iterable -
Returns:: a new Stream formed applying the given Applicable2 to each pair this Stream and the given iterable. The resulting Stream size is the minimum of both iterables sizes, or infinite, if both this and iterable are
See Also:: Iterables.zip(Iterable, Iterable), zip(Iterable, Function2)

zip

<B> Stream<Tuple2<A,B>> zip(@NonNull
                            Iterator<B> other)

Returns a Stream formed by by pair of element from this and the given Iterator. If either this or other is shorter than the other one, the remaining elements are discarded.

Type Parameters:: B -
Parameters:: other -
Returns:: a new Stream formed applying the given Applicable2 to each pair this Stream and the given iterator. The resulting Stream size is the minimum of both iterables sizes, or infinite, if both this and other are
Since:: 2.2
See Also:: Iterables.zip(Iterable, Iterable), zip(Iterable, Function2)

print

void print(Appendable destination)
           throws IOException

Prints the stream elements to an appendable, like StringBuilder or a Writer

Parameters:: destination - the appendable were print stream elements
Throws:: IOException - if any io error occurs

print

void print()

Prints the stream elements to System.out

Throws:: IOException - if any io error occurs

println

void println(Appendable o)
             throws IOException

Prints the stream elements to an appendable, like StringBuilder or a Writer, followed by a newline character

Parameters:: destination - the appendable were print stream elements
Throws:: IOException - if any io error occurs

println

void println()

Prints the stream elements to System.out, followed by a newline character. Equivalent to println(System.out)

Throws:: IOException - if any io error occurs

printString

String printString()

Prints the stream elements to a string

Returns:: a string with the stream elements

toSet

@NonNull
Set<A> toSet()

Converts this Stream into a Set, by adding all its elements to a new Set. The resulting Set is Serializable and non-lazy.

Returns:: a new Set that contains all elements retrieved from this Stream

toList

@NonNull
List<A> toList()

* Converts this Stream into a List, by adding all its elements to a new List. The resulting List is Serializable and non-lazy.

Returns:: a new List that contains all elements retrieved from this Stream

toArray

@NonNull
A[] toArray(@NonNull
                    Class<? super A> clazz)

Creates a new array that has the same elements that the retrived by this Stream

Parameters:: clazz - the array component class
Returns:: a new array

memorize

@Deprecated
@Repeatable
@Projection
Stream<A> memorize()

Deprecated. the exact name of this concept is memoization, not memorization. Use memoize() instead

Equivalent to memoize()

memoize

@Repeatable
@Projection
Stream<A> memoize()

Memoizes stream elements and their order, by answering a lazy stream with Repeatable iteration order that caches elements evaluated during iteration.

Returns:: a new Stream that memoizes elements evaluated during iteration
Since:: 2.2

force

@NonNull
@Repeatable
Stream<A> force()

Forces stream elements evaluation by converting it into a new ordered stream one that is not lazy and that has repeatable iteration order.

Returns:: a new Stream that retrieves elements from the next iteration of this Stream.

intersperse

@Projection
Stream<A> intersperse(A element)

Inserts the given element between each retrieved element of this Stream

Parameters:: element -
Returns:: a new Stream

incorporate

@Projection
Stream<A> incorporate(@NonNull
                                 Function<? super A,? extends A> function)

Inserts after each element the result of applying the given function to it. For example:

 Streams.cons(10, 9, 90).incorporate(integer().negate()).equiv(10, -10, 9, -9, 90, -90);

Parameters:: function -
Returns:: a new Stream
Since:: 1.2

incorporate

@Projection
Stream<A> incorporate(@NonNull
                                 A element)

Inserts the given value after each element of the stream. This message is similar to intersperse(Object), but inserts the value also at the end of the stream.

Parameters:

element - Example:

 Streams.cons('a', 'b', 'c').incorporate('d').equiv('a', 'd', 'b', 'd', 'c', 'd');

Returns:

a new Stream

Since:

1.2

groupOn

@NonNull
<K,V> Map<K,V> groupOn(Applicable<? super A,K> groupFunction,
                               Reduction<A,V> reduction)

Groups elements by the given groupingFunction, and reduces each group using the given reduction.

The grouping is performed so that two elements a and b will be put in the same group if and only if groupFunction.apply(a).equals(groupFunction.apply(b))

Type Parameters:: K -
Parameters:: groupFunction -; reduction -
Returns:: a Map with an entry for each group, where its key is the result of the grouping function, and the value is the result of the reduction of the elements for that group

cross

@Projection
Stream<Tuple2<A,A>> cross()

Answers the Cartesian product of this stream and itself

Parameters:: other -
Returns:: a new Stream projection
See Also:: Iterables.cross(Iterable, Iterable)

cross

@Projection
<B> Stream<Tuple2<A,B>> cross(@NonNull
                                         Stream<B> other)

Answers the Cartesian product of this stream and the given one

Type Parameters:: B -
Parameters:: other -
Returns:: a new Stream projection
See Also:: Iterables.cross(Iterable, Iterable)

cross

@Projection
<B> Stream<Tuple2<A,B>> cross(@NonNull
                                         Iterable<B> other)

Answers the cartesian product of this Stream and the given Iterable

Type Parameters:: B -
Parameters:: other -
Returns:: cross(Streams.from(other))
See Also:: cross(Stream)

cross

<B> Stream<Tuple2<A,B>> cross(@NonNull
                              B... elements)

Answers the cartesian product of this Stream and the given elements. Example:

 //Answers true
 Streams
   .cons("male", "female")
   .cross("young", "middle-aged", "old")
   .equiv(
     _("male", "young"),
     _("male", "middle-aged"),
     _("male", "old"),
     _("female", "young"),
     _("female", "middle-aged"),
     _("female", "old"));

Type Parameters:: B -
Parameters:: other -
Returns:: cross(Streams.cons(elements))
Since:: 2.2
See Also:: cross(Stream)

cross

@Projection
<B> Stream<Tuple2<A,B>> cross(@NonNull
                                         Iterator<B> other)

Answers the cartesian product of this Stream and the given Iterator

Type Parameters:: B -
Parameters:: other -
Returns:: cross(Streams.from(other))
Since:: 2.2
See Also:: cross(Stream)

crossStreams

@Projection
Stream<Stream<A>> crossStreams(@NonNull
                                          Stream<Stream<A>> streamOfStreams)

Answers the cartesian product of this Stream and each one of the given streamOfStreams

Parameters:: streamOfStreams -
Returns:: a new Stream projection

transform

@Projection
<B> Stream<B> transform(@NonNull
                                   Applicable<Stream<A>,? extends Stream<B>> function)

Lazily applies the given function to this Stream.

Type Parameters:: B -
Parameters:: function - the function to apply to this stream
Returns:: a new stream that will retrieve elements from the result of applying the given function to this stream

transform

@Projection
<B> Stream<B> transform(@NonNull
                                   Stream.DeconsApplicable<A,B> function)

Lazily applies the given function to this stream, deconstructing this stream into head and tail, or into an empty stream. Unlike transform(Applicable), whose function will receive the whole stream, the given Stream.DeconsApplicable, when applied, will take the head and tail of this Stream, if non empty, or no arguments, if the stream is empty.

Type Parameters:: B -
Parameters:: function -
Returns:: a new stream that will retrieve elements from the result of applying the given function to this stream
See Also:: decons()

transform

@Projection
<B> Stream<B> transform(@NonNull
                                   Stream.DelayedDeconsApplicable<A,B> function)

Lazily applies the given function to this stream, deconstructing this stream into a head thunk and tail, or into an empty stream. Unlike transform(Applicable), whose function will receive the whole stream, the given Stream.DeconsApplicable, when applied, will take a head's thunk and tail of this Stream, if non empty, or no arguments, if the stream is empty.

Type Parameters:: B -
Parameters:: function -
Returns:: a new stream that will retrieve elements from the result of applying the given function to this stream
See Also:: delayedDecons()

first

A first()
        throws EmptySourceException

Answers the first element. This is equivalent to head(). It is also equivalent to get(0), but throws a EmptySourceException if stream is empty

Returns:: head()
Throws:: EmptySourceException - if there is no first element

second

A second()
         throws NoSuchElementException

Answers the second element. This is equivalent to get(1), but throws a NoSuchElementException if stream size < 2

Returns:: get(1)
Throws:: NoSuchElementException - if there is no second element

third

A third()
        throws NoSuchElementException

Answers the third element. This is equivalent to get(2), but throws a NoSuchElementException if stream size < 3

Returns:: get(2)
Throws:: IndexOutOfBoundsException - if there is no third element; NoSuchElementException

last

A last()
       throws EmptySourceException

Answers the last element of this stream. This method only works with finite streams

Returns:: the last element
Throws:: EmptySourceException

isBefore

boolean isBefore(A previous,
                 A next)

Answers if both arguments are contained by this stream, and the first one is before the second one. This method works even for stream that can be iterated only once

Parameters:: previous -; next -
Returns:: whether both elements are contained by this Stream, and the first is before the second one.
See Also:: containsBefore(Object, Object)

containsBefore

boolean containsBefore(A element,
                       A reference)

Answers if element is contained by this stream, and its first occurence is before the first occurence of the second one, if any.

This message is similar to isBefore(Object, Object), but may be true even if the reference is not present at the stream. It will be always true if both element and reference are equal, too.

Examples:

  Streams.from("abcd").containsBefore('c', 'a'); //false. c is after a
  Streams.from("abcd").containsBefore('x', 'd'); //false. x is not present
  Streams.from("abcd").containsBefore('a', 'b'); //true
  Streams.from("abcd").containsBefore('b', 'd'); //true
  Streams.from("abcd").containsBefore('a', 'a'); //true
  Streams.from("abcd").containsBefore('x', 'x'); //false. x is not present

Parameters:: element - the element to test whether it is contained by this stream, and appears before reference; reference -
Returns:: whether both elements are contained by this Stream, and the first is before the second one.
Since:: 2.2
See Also:: insertBefore(Object, Object), isBefore(Object, Object)

containsBeforeIndex

boolean containsBeforeIndex(A element,
                            @NotNegative
                            int index)

Answers if element is contained by this stream, and its first occurence is before the given index. As a particular case, if index is 0, return always false

Examples:

   Streams.from("abcd").containsBeforeIndex('x', 2); //false. x is not present
   Streams.from("abcd").containsBeforeIndex('c', 1); //false. c is present but at index 2
   Streams.from("abcd").containsBeforeIndex('a', 0); //false. a is present but at index 0
   Streams.from("abcd").containsBeforeIndex('a', 1); //true
   Streams.from("abcd").containsBeforeIndex('b', 3); //true
   Streams.from("abcd").containsBeforeIndex('b', 40); //true

Parameters:: element -; index -
Returns:: whether elements is containted and before index
Since:: 2.2
See Also:: insertBeforeIndex(Object, int)

get

A get(int n)

Answers the n-th element.

Parameters:: n -
Returns:: the n-th element, zero based
Throws:: IndexOutOfBoundsException - if there is no n-th element, because stream has less than n elements

indexOf

int indexOf(A element)

Answers the zero-based index of the given element

Parameters:: element -
Returns:: the index of the element first element equal to element, or -1, if it is not contained by this stream

findIndex

int findIndex(Evaluable<? super A> predicate)

Answers the zero-based index of first element that matches the given predicate

Parameters:: predicate -
Returns:: the index of the first element that evaluates the predicate to true, or -1, if no element satisfies it
Since:: 2.1

indices

@Projection
Stream<Integer> indices(Evaluable<? super A> predicate)

Answers a stream containing all the zero-based indices of the elements that matches the given predicate

Parameters:: predicate -
Returns:: a Stream with the indices of the elements that satisfy the given predicate
Since:: 2.1

positionOf

int positionOf(A element)
               throws NoSuchElementException

Answers the index of the given present element. This method behaves exactly like indexOf(Object), with the only difference that it will throw a NoSuchElementException if the given element is not present on the stream

Parameters:: element -
Returns:: the index of the given element
Throws:: NoSuchElementException - if the element is no contained by this Stream

findPosition

int findPosition(Evaluable<? super A> predicate)
                 throws NoSuchElementException

Answers the zero-based index of first, present element that matches the given predicate. This method behaves exactly like findIndex(Evaluable), with the only difference that it will throw a NoSuchElementException if the given element is not present on the stream

Parameters:: predicate -
Returns:: the index of the first element that evaluates the predicate
Throws:: NoSuchElementException - if no elements satisfies the given predicate
Since:: 2.1

filterIndex

@Projection
Stream<A> filterIndex(@NonNull
                                 Evaluable<Integer> predicate)

Preserves elements that whose index satisfy the given predicate

Parameters:: predicate -
Returns:: a new Stream projection that will retrieve only elements whose index evaluate to true

skipIndex

@Projection
Stream<A> skipIndex(int index)

Answers a streams that retrieves all the elements of this one, except of that at the given index

Parameters:: predicate -
Returns:: a new Stream that skips the element at the given index

decons

@NonNull
Tuple2<A,Stream<A>> decons()
                           throws EmptySourceException

Answers this stream split into head and tail. This method is preferred over head() and tail(), as it will work as expected even on non repeatable iteration streams.

Returns:: a pair containing the head and the tail of this stream. The tail is NonNull and a Projection, but it is always non-repeatable.
Throws:: EmptySourceException - if stream is empty

delayedDecons

@NonNull
Tuple2<Thunk<A>,Stream<A>> delayedDecons()
                                         throws EmptySourceException

Answers this non-empty stream split into a head thunk and tail. This method is preferred over decons() when the head value of the Stream is potentially irrelevant, as this methods grants to suceeds even in those cases where head() fails.

Returns:: a pair containing a thunk that will provide the head, and the tail of this stream. The tail is NonNull and a Projection, but it is always non-repeatable.
Throws:: EmptySourceException - if stream is empty

head

A head()
       throws EmptySourceException

Answers the head of the Stream, which is the first element of the stream. However, if you need both head and tail in order to perfom functional-style transformations over the stream, consider using decons().

Returns:: first()
Throws:: EmptySourceException - if stream is empty

tail

@Projection
Stream<A> tail()
               throws EmptySourceException

Answers the tail of the Stream

Returns:: an Stream that retrieves all its elements, except of the first one
Throws:: EmptySourceException - if stream is empty

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

net.sf.staccatocommons.collections.stream Interface Stream<A>

iterator

forEach

each

map

filter

skip

takeWhile

take

dropWhile

drop

slice

partition

streamPartition

map

flatMap

flatMapArray

reverse

any

anyOrNone

anyOrNull

anyOrElse

anyOrElse

find

findOrNone

findOrNull

findOrElse

findOrElse

all

allEquiv

allEquivBy

any

equiv

equiv

equiv

equivBy

equivBy

equivBy

equivOn

equivOn

equivOn

fold

reduce

reduce

joinStrings

sum

product

average

countOf

sort

sortBy

sortOn

minimumBy

minimumOn

minimum

maximumBy

maximumOn

maximum

append

concat

concat

concat

appendUndefined

append

append

delayedAppend

prepend

prepend

delayedPrepend

insertBeforeIndex

insertBefore

clone

branch

zipWith

zipWith

zipWith

zip

zip

zip

zip

net.sf.staccatocommons.collections.stream
Interface Stream<A>