Copyright Tony Morris 2008

This software is released under an open source BSD licence.

fj.data
Class Stream<A>

java.lang.Object
  extended by fj.data.Stream<A>
All Implemented Interfaces:
Iterable<A>

public abstract class Stream<A>
extends Object
implements Iterable<A>

A lazy (not yet evaluated), immutable, singly linked list.

Version:
2.19

Method Summary
 Stream<A> append(P1<Stream<A>> as)
          Appends the given stream to this stream.
 Stream<A> append(Stream<A> as)
          Appends the given stream to this stream.
<B> Stream<B>
apply(Stream<F<A,B>> sf)
          Performs function application within a stream (applicative functor pattern).
<B> Stream<B>
bind(F<A,Stream<B>> f)
          Binds the given function across each element of this stream with a final join.
<B,C> Stream<C>
bind(Stream<B> sb, F<A,F<B,C>> f)
          Binds the given function across each element of this stream and the given stream with a final join.
<B,C,D> Stream<D>
bind(Stream<B> sb, Stream<C> sc, F<A,F<B,F<C,D>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B,C,D,E> Stream<E>
bind(Stream<B> sb, Stream<C> sc, Stream<D> sd, F<A,F<B,F<C,F<D,E>>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B,C,D,E,F$>
Stream<F$>
bind(Stream<B> sb, Stream<C> sc, Stream<D> sd, Stream<E> se, F<A,F<B,F<C,F<D,F<E,F$>>>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B,C,D,E,F$,G>
Stream<G>
bind(Stream<B> sb, Stream<C> sc, Stream<D> sd, Stream<E> se, Stream<F$> sf, F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B,C,D,E,F$,G,H>
Stream<H>
bind(Stream<B> sb, Stream<C> sc, Stream<D> sd, Stream<E> se, Stream<F$> sf, Stream<G> sg, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B,C,D,E,F$,G,H,I>
Stream<I>
bind(Stream<B> sb, Stream<C> sc, Stream<D> sd, Stream<E> se, Stream<F$> sf, Stream<G> sg, Stream<H> sh, F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)
          Binds the given function across each element of this stream and the given streams with a final join.
<B> Stream<B>
cobind(F<Stream<A>,B> k)
          Binds the given function across the stream of tails of this stream (Comonad pattern).
static
<A> F<A,F<Stream<A>,Stream<A>>>
cons_()
          Returns a function that prepends (cons) an element to a stream to produce a new stream.
static
<A> F<A,F<P1<Stream<A>>,Stream<A>>>
cons()
          Returns a function that prepends (cons) an element to a stream to produce a new stream.
 Stream<A> cons(A a)
          Prepends (cons) the given element to this stream to product a new stream.
static
<A> Stream<A>
cons(A head, P1<Stream<A>> tail)
          Prepends the given head element to the given tail element to produce a new stream.
static
<A> Stream<A>
cycle(Stream<A> as)
          Returns an infinite-length stream of the given elements cycling.
 Stream<A> drop(int i)
          Drops the given number of elements from the head of this stream if they are available.
 Stream<A> dropWhile(F<A,Boolean> f)
          Removes elements from the head of this stream that do not match the given predicate function until an element is found that does match or the stream is exhausted.
 boolean exists(F<A,Boolean> f)
          Returns true if the predicate holds for at least one of the elements of this stream, false otherwise (false for the empty stream).
static
<A> F<F<A,Boolean>,F<Stream<A>,Stream<A>>>
filter()
          Returns a first-class version of the filter function.
 Stream<A> filter(F<A,Boolean> f)
          Filters elements from this stream by returning only elements which produce true when the given function is applied to them.
 Option<A> find(F<A,Boolean> f)
          Finds the first occurrence of an element that matches the given predicate or no value if no elements match.
<B> B
foldLeft(F<B,F<A,B>> f, B b)
          Performs a left-fold reduction across this stream.
<B> B
foldLeft(F2<B,A,B> f, B b)
          Performs a left-fold reduction across this stream.
 A foldLeft1(F<A,F<A,A>> f)
          Takes the first 2 elements of the stream and applies the function to them, then applies the function to the result and the third element and so on.
 A foldLeft1(F2<A,A,A> f)
          Takes the first 2 elements of the stream and applies the function to them, then applies the function to the result and the third element and so on.
<B> B
foldRight(F<A,F<P1<B>,B>> f, B b)
          Performs a right-fold reduction across this stream.
<B> B
foldRight(F2<A,P1<B>,B> f, B b)
          Performs a right-fold reduction across this stream.
<B> B
foldRight1(F<A,F<B,B>> f, B b)
          Performs a right-fold reduction across this stream.
<B> B
foldRight1(F2<A,B,B> f, B b)
          Performs a right-fold reduction across this stream.
 boolean forall(F<A,Boolean> f)
          Returns true if the predicate holds for all of the elements of this stream, false otherwise (true for the empty stream).
 void foreach(Effect<A> f)
          Performs a side-effect for each element of this stream.
 Unit foreach(F<A,Unit> f)
          Performs a side-effect for each element of this stream.
static
<A> Stream<A>
forever(Enumerator<A> e, A from)
          Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at increments of 1.
static
<A> Stream<A>
forever(Enumerator<A> e, A from, long step)
          Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at the given increment.
static
<A,B> Stream<A>
fromFunction(Enumerator<B> e, F<B,A> f, B i)
          Converts a function of an enumerable type to a stream of the results of that function, starting at the given index.
static
<A> Stream<A>
fromFunction(F<Natural,A> f)
          Converts a function of natural numbers to a stream.
abstract  A head()
          The first element of the stream or fails for the empty stream.
 A index(int i)
          Returns the element at the given index if it exists, fails otherwise.
 Stream<A> interleave(Stream<A> as)
          Interleaves the given stream with this stream to produce a new stream.
static
<A> F<Stream<A>,Boolean>
isEmpty_()
          Returns a function that determines whether a given stream is empty.
 boolean isEmpty()
          Returns true if this stream is empty, false otherwise.
static
<A> F<Stream<A>,Boolean>
isNotEmpty_()
          Returns a function that determines whether a given stream is not empty.
 boolean isNotEmpty()
          Returns false if this stream is empty, true otherwise.
static
<A> Stream<A>
iterableStream(Iterable<A> i)
          Takes the given iterable to a stream.
static
<A> F<F<A,A>,F<A,Stream<A>>>
iterate()
          A first-class version of the iterate function.
static
<A> Stream<A>
iterate(F<A,A> f, A a)
          Returns a stream constructed by applying the given iteration function starting at the given value.
 Iterator<A> iterator()
          Returns an iterator for this stream.
static
<A> F<Stream<Stream<A>>,Stream<A>>
join()
          A first-class version of join
static
<A> Stream<A>
join(Stream<Stream<A>> o)
          Joins the given stream of streams using a bind operation.
 int length()
          The length of this stream.
static
<A,B> F<F<A,B>,F<Stream<A>,Stream<B>>>
map_()
          Provides a first-class version of the map function.
<B> Stream<B>
map(F<A,B> f)
          Maps the given function across this stream.
static
<A> P1<Stream<A>>
nil_()
          Returns an empty stream.
static
<A> Stream<A>
nil()
          Returns an empty stream.
 A orHead(P1<A> a)
          Returns the head of this stream if there is one or the given argument if this stream is empty.
 P1<Stream<A>> orTail(P1<Stream<A>> as)
          Returns the tail of this stream if there is one or the given argument if this stream is empty.
 Stream<A> qsort(Ord<A> o)
          Sort this stream according to the given ordering, using the Quick Sort algorithm.
 Stream<A> qsort(Ord<A> o, Strategy<Unit> s)
          Sort this stream according to the given ordering, using a parallel Quick Sort algorithm that uses the given parallelisation strategy.
static
<A> Stream<A>
range(Enumerator<A> e, A from, A to)
          Returns a stream using the given enumerator from the given value to the other given value stepping at increments of 1.
static
<A> Stream<A>
range(Enumerator<A> e, A from, A to, long step)
          Returns a stream using the given enumerator from the given value to the other given value stepping at the given increment.
static Stream<Integer> range(int from)
          Returns an infinite stream of integers from the given from value (inclusive).
static Stream<Integer> range(int from, int to)
          Returns a stream of integers from the given from value (inclusive) to the given to value (exclusive).
static
<A> Stream<A>
repeat(A a)
          Returns an infinite-length stream of the given element.
 Stream<A> reverse()
          Reverse this stream in constant stack space.
<B> Stream<B>
sequence(Stream<B> bs)
          Performs a bind across each stream element, but ignores the element value each time.
<B> Stream<B>
sequenceW(Stream<F<Stream<A>,B>> fs)
          Applies a stream of comonadic functions to this stream, returning a stream of values.
static
<A> F<A,Stream<A>>
single()
          Returns a function that yields a stream containing its argument.
static
<A> Stream<A>
single(A a)
          Returns a stream of one element containing the given value.
 Stream<A> snoc(P1<A> a)
          Append the given element to this stream to product a new stream.
static
<A> Stream<A>
stream(A... as)
          Constructs a stream with the given elements.
<B> B
stream(B nil, F<A,F<P1<Stream<A>>,B>> cons)
          Performs a reduction on this stream using the given arguments.
abstract  P1<Stream<A>> tail()
          The stream without the first element or fails for the empty stream.
 Stream<Stream<A>> tails()
          Returns a stream of the tails of this stream.
 Stream<A> take(int n)
          Returns the first n elements from the head of this stream.
 Stream<A> takeWhile(F<A,Boolean> f)
          Returns the first elements of the head of this stream that match the given predicate function.
 Array<A> toArray()
          Returns a array projection of this stream.
 Array<A> toArray(Class<A[]> c)
          Returns a array projection of this stream.
 Collection<A> toCollection()
          Projects an immutable collection of this stream.
<X> Either<X,A>
toEither(P1<X> x)
          Returns an either projection of this stream; the given argument in Left if empty, or the first element in Right.
 F<Integer,A> toFunction()
          Converts this stream to a function of natural numbers.
 List<A> toList()
          Returns a list projection of this stream.
 Option<A> toOption()
          Returns an option projection of this stream; None if empty, or the first element in Some.
static
<A,B> Stream<A>
unfold(F<B,Option<P2<A,B>>> f, B b)
          Unfolds across the given function starting at the given value to produce a stream.
static
<A,B> P2<Stream<A>,Stream<B>>
unzip(Stream<P2<A,B>> xs)
          Transforms a stream of pairs into a stream of first components and a stream of second components.
<B> Stream<B>
zapp(Stream<F<A,B>> fs)
          Zips this stream with the given stream of functions, applying each function in turn to the corresponding element in this stream to produce a new stream.
<B> Stream<P2<A,B>>
zip(Stream<B> bs)
          Zips this stream with the given stream to produce a stream of pairs.
 Stream<P2<A,Integer>> zipIndex()
          Zips this stream with the index of its element as a pair.
static
<A,B,C> F<Stream<A>,F<Stream<B>,F<F<A,F<B,C>>,Stream<C>>>>
zipWith()
          A first-class version of the zipWith function.
<B,C> Stream<C>
zipWith(Stream<B> bs, F<A,F<B,C>> f)
          Zips this stream with the given stream using the given function to produce a new stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

iterator

public Iterator<A> iterator()
Returns an iterator for this stream. This method exists to permit the use in a for-each loop.

Specified by:
iterator in interface Iterable<A>
Returns:
A iterator for this stream.

head

public abstract A head()
The first element of the stream or fails for the empty stream.

Returns:
The first element of the stream or fails for the empty stream.

tail

public abstract P1<Stream<A>> tail()
The stream without the first element or fails for the empty stream.

Returns:
The stream without the first element or fails for the empty stream.

isEmpty

public boolean isEmpty()
Returns true if this stream is empty, false otherwise.

Returns:
true if this stream is empty, false otherwise.

isNotEmpty

public boolean isNotEmpty()
Returns false if this stream is empty, true otherwise.

Returns:
false if this stream is empty, true otherwise.

stream

public <B> B stream(B nil,
                    F<A,F<P1<Stream<A>>,B>> cons)
Performs a reduction on this stream using the given arguments.

Parameters:
nil - The value to return if this stream is empty.
cons - The function to apply to the head and tail of this stream if it is not empty.
Returns:
A reduction on this stream.

foldRight

public <B> B foldRight(F<A,F<P1<B>,B>> f,
                       B b)
Performs a right-fold reduction across this stream. This function uses O(length) stack space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the right-fold reduction.

foldRight

public <B> B foldRight(F2<A,P1<B>,B> f,
                       B b)
Performs a right-fold reduction across this stream. This function uses O(length) stack space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the right-fold reduction.

foldRight1

public <B> B foldRight1(F<A,F<B,B>> f,
                        B b)
Performs a right-fold reduction across this stream. This function uses O(length) stack space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the right-fold reduction.

foldRight1

public <B> B foldRight1(F2<A,B,B> f,
                        B b)
Performs a right-fold reduction across this stream. This function uses O(length) stack space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the right-fold reduction.

foldLeft

public <B> B foldLeft(F<B,F<A,B>> f,
                      B b)
Performs a left-fold reduction across this stream. This function runs in constant space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the left-fold reduction.

foldLeft

public <B> B foldLeft(F2<B,A,B> f,
                      B b)
Performs a left-fold reduction across this stream. This function runs in constant space.

Parameters:
f - The function to apply on each element of the stream.
b - The beginning value to start the application from.
Returns:
The final result after the left-fold reduction.

foldLeft1

public A foldLeft1(F2<A,A,A> f)
Takes the first 2 elements of the stream and applies the function to them, then applies the function to the result and the third element and so on.

Parameters:
f - The function to apply on each element of the stream.
Returns:
The final result after the left-fold reduction.

foldLeft1

public A foldLeft1(F<A,F<A,A>> f)
Takes the first 2 elements of the stream and applies the function to them, then applies the function to the result and the third element and so on.

Parameters:
f - The function to apply on each element of the stream.
Returns:
The final result after the left-fold reduction.

orHead

public A orHead(P1<A> a)
Returns the head of this stream if there is one or the given argument if this stream is empty.

Parameters:
a - The argument to return if this stream is empty.
Returns:
The head of this stream if there is one or the given argument if this stream is empty.

orTail

public P1<Stream<A>> orTail(P1<Stream<A>> as)
Returns the tail of this stream if there is one or the given argument if this stream is empty.

Parameters:
as - The argument to return if this stream is empty.
Returns:
The tail of this stream if there is one or the given argument if this stream is empty.

map

public <B> Stream<B> map(F<A,B> f)
Maps the given function across this stream.

Parameters:
f - The function to map across this stream.
Returns:
A new stream after the given function has been applied to each element.

map_

public static <A,B> F<F<A,B>,F<Stream<A>,Stream<B>>> map_()
Provides a first-class version of the map function.

Returns:
A function that maps a given function across a given stream.

foreach

public Unit foreach(F<A,Unit> f)
Performs a side-effect for each element of this stream.

Parameters:
f - The side-effect to perform for the given element.
Returns:
The unit value.

foreach

public void foreach(Effect<A> f)
Performs a side-effect for each element of this stream.

Parameters:
f - The side-effect to perform for the given element.

filter

public Stream<A> filter(F<A,Boolean> f)
Filters elements from this stream by returning only elements which produce true when the given function is applied to them.

Parameters:
f - The predicate function to filter on.
Returns:
A new stream whose elements all match the given predicate.

append

public Stream<A> append(Stream<A> as)
Appends the given stream to this stream.

Parameters:
as - The stream to append to this one.
Returns:
A new stream that has appended the given stream.

append

public Stream<A> append(P1<Stream<A>> as)
Appends the given stream to this stream.

Parameters:
as - The stream to append to this one.
Returns:
A new stream that has appended the given stream.

bind

public <B> Stream<B> bind(F<A,Stream<B>> f)
Binds the given function across each element of this stream with a final join.

Parameters:
f - The function to apply to each element of this stream.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C> Stream<C> bind(Stream<B> sb,
                            F<A,F<B,C>> f)
Binds the given function across each element of this stream and the given stream with a final join.

Parameters:
sb - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given stream.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D> Stream<D> bind(Stream<B> sb,
                              Stream<C> sc,
                              F<A,F<B,F<C,D>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D,E> Stream<E> bind(Stream<B> sb,
                                Stream<C> sc,
                                Stream<D> sd,
                                F<A,F<B,F<C,F<D,E>>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
sd - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D,E,F$> Stream<F$> bind(Stream<B> sb,
                                    Stream<C> sc,
                                    Stream<D> sd,
                                    Stream<E> se,
                                    F<A,F<B,F<C,F<D,F<E,F$>>>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
sd - A given stream to bind the given function with.
se - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D,E,F$,G> Stream<G> bind(Stream<B> sb,
                                     Stream<C> sc,
                                     Stream<D> sd,
                                     Stream<E> se,
                                     Stream<F$> sf,
                                     F<A,F<B,F<C,F<D,F<E,F<F$,G>>>>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
sd - A given stream to bind the given function with.
se - A given stream to bind the given function with.
sf - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H> Stream<H> bind(Stream<B> sb,
                                       Stream<C> sc,
                                       Stream<D> sd,
                                       Stream<E> se,
                                       Stream<F$> sf,
                                       Stream<G> sg,
                                       F<A,F<B,F<C,F<D,F<E,F<F$,F<G,H>>>>>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
sd - A given stream to bind the given function with.
se - A given stream to bind the given function with.
sf - A given stream to bind the given function with.
sg - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

bind

public <B,C,D,E,F$,G,H,I> Stream<I> bind(Stream<B> sb,
                                         Stream<C> sc,
                                         Stream<D> sd,
                                         Stream<E> se,
                                         Stream<F$> sf,
                                         Stream<G> sg,
                                         Stream<H> sh,
                                         F<A,F<B,F<C,F<D,F<E,F<F$,F<G,F<H,I>>>>>>>> f)
Binds the given function across each element of this stream and the given streams with a final join.

Parameters:
sb - A given stream to bind the given function with.
sc - A given stream to bind the given function with.
sd - A given stream to bind the given function with.
se - A given stream to bind the given function with.
sf - A given stream to bind the given function with.
sg - A given stream to bind the given function with.
sh - A given stream to bind the given function with.
f - The function to apply to each element of this stream and the given streams.
Returns:
A new stream after performing the map, then final join.

sequence

public <B> Stream<B> sequence(Stream<B> bs)
Performs a bind across each stream element, but ignores the element value each time.

Parameters:
bs - The stream to apply in the final join.
Returns:
A new stream after the final join.

apply

public <B> Stream<B> apply(Stream<F<A,B>> sf)
Performs function application within a stream (applicative functor pattern).

Parameters:
sf - The stream of functions to apply.
Returns:
A new stream after applying the given stream of functions through this stream.

interleave

public Stream<A> interleave(Stream<A> as)
Interleaves the given stream with this stream to produce a new stream.

Parameters:
as - The stream to interleave this stream with.
Returns:
A new stream with elements interleaved from this stream and the given stream.

qsort

public Stream<A> qsort(Ord<A> o)
Sort this stream according to the given ordering, using the Quick Sort algorithm.

Parameters:
o - An ordering for the elements of this stream.
Returns:
A new stream with the elements of this stream sorted according to the given ordering.

qsort

public Stream<A> qsort(Ord<A> o,
                       Strategy<Unit> s)
Sort this stream according to the given ordering, using a parallel Quick Sort algorithm that uses the given parallelisation strategy.

Parameters:
o - An ordering for the elements of this stream.
s - A strategy for parallelising the algorithm.
Returns:
A new stream with the elements of this stream sorted according to the given ordering.

toCollection

public Collection<A> toCollection()
Projects an immutable collection of this stream.

Returns:
An immutable collection of this stream.

range

public static Stream<Integer> range(int from,
                                    int to)
Returns a stream of integers from the given from value (inclusive) to the given to value (exclusive).

Parameters:
from - The minimum value for the stream (inclusive).
to - The maximum value for the stream (exclusive).
Returns:
A stream of integers from the given from value (inclusive) to the given to value (exclusive).

stream

public static <A> Stream<A> stream(A... as)
Constructs a stream with the given elements.

Parameters:
as - The elements which which to construct a stream.
Returns:
a new stream with the given elements.

forever

public static <A> Stream<A> forever(Enumerator<A> e,
                                    A from)
Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at increments of 1.

Parameters:
e - The enumerator to compute successors from.
from - The value to begin computing successors from.
Returns:
A stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at increments of 1.

forever

public static <A> Stream<A> forever(Enumerator<A> e,
                                    A from,
                                    long step)
Returns a stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at the given increment.

Parameters:
e - The enumerator to compute successors from.
from - The value to begin computing successors from.
step - The increment to step.
Returns:
A stream that is either infinite or bounded up to the maximum value of the given iterator starting at the given value and stepping at the given increment.

range

public static <A> Stream<A> range(Enumerator<A> e,
                                  A from,
                                  A to)
Returns a stream using the given enumerator from the given value to the other given value stepping at increments of 1.

Parameters:
e - The enumerator to compute successors from.
from - The value to begin computing successors from.
to - The value to stop computing successors from.
Returns:
A stream using the given enumerator from the given value to the other given value stepping at increments of 1.

range

public static <A> Stream<A> range(Enumerator<A> e,
                                  A from,
                                  A to,
                                  long step)
Returns a stream using the given enumerator from the given value to the other given value stepping at the given increment.

Parameters:
e - The enumerator to compute successors from.
from - The value to begin computing successors from.
to - The value to stop computing successors from.
step - The increment to step.
Returns:
A stream using the given enumerator from the given value to the other given value stepping at the given increment.

range

public static Stream<Integer> range(int from)
Returns an infinite stream of integers from the given from value (inclusive).

Parameters:
from - The minimum value for the stream (inclusive).
Returns:
A stream of integers from the given from value (inclusive).

filter

public static <A> F<F<A,Boolean>,F<Stream<A>,Stream<A>>> filter()
Returns a first-class version of the filter function.

Returns:
a function that filters a given stream using a given predicate.

zapp

public <B> Stream<B> zapp(Stream<F<A,B>> fs)
Zips this stream with the given stream of functions, applying each function in turn to the corresponding element in this stream to produce a new stream. If this stream and the given stream have different lengths, then the longer stream is normalised so this function never fails.

Parameters:
fs - The stream of functions to apply to this stream.
Returns:
A new stream with a length the same as the shortest of this stream and the given stream.

zipWith

public <B,C> Stream<C> zipWith(Stream<B> bs,
                               F<A,F<B,C>> f)
Zips this stream with the given stream using the given function to produce a new stream. If this stream and the given stream have different lengths, then the longer stream is normalised so this function never fails.

Parameters:
bs - The stream to zip this stream with.
f - The function to zip this stream and the given stream with.
Returns:
A new stream with a length the same as the shortest of this stream and the given stream.

zip

public <B> Stream<P2<A,B>> zip(Stream<B> bs)
Zips this stream with the given stream to produce a stream of pairs. If this stream and the given stream have different lengths, then the longer stream is normalised so this function never fails.

Parameters:
bs - The stream to zip this stream with.
Returns:
A new stream with a length the same as the shortest of this stream and the given stream.

zipIndex

public Stream<P2<A,Integer>> zipIndex()
Zips this stream with the index of its element as a pair.

Returns:
A new stream with the same length as this stream.

toEither

public <X> Either<X,A> toEither(P1<X> x)
Returns an either projection of this stream; the given argument in Left if empty, or the first element in Right.

Parameters:
x - The value to return in left if this stream is empty.
Returns:
An either projection of this stream.

toOption

public Option<A> toOption()
Returns an option projection of this stream; None if empty, or the first element in Some.

Returns:
An option projection of this stream.

toList

public List<A> toList()
Returns a list projection of this stream.

Returns:
A list projection of this stream.

toArray

public Array<A> toArray()
Returns a array projection of this stream.

Returns:
A array projection of this stream.

toArray

public Array<A> toArray(Class<A[]> c)
Returns a array projection of this stream.

Parameters:
c - The class type of the array to return.
Returns:
A array projection of this stream.

cons

public Stream<A> cons(A a)
Prepends (cons) the given element to this stream to product a new stream.

Parameters:
a - The element to prepend.
Returns:
A new stream with the given element at the head.

snoc

public Stream<A> snoc(P1<A> a)
Append the given element to this stream to product a new stream.

Parameters:
a - The element to append.
Returns:
A new stream with the given element at the end.

take

public Stream<A> take(int n)
Returns the first n elements from the head of this stream.

Parameters:
n - The number of elements to take from this stream.
Returns:
The first n elements from the head of this stream.

drop

public Stream<A> drop(int i)
Drops the given number of elements from the head of this stream if they are available.

Parameters:
i - The number of elements to drop from the head of this stream.
Returns:
A stream with a length the same, or less than, this stream.

takeWhile

public Stream<A> takeWhile(F<A,Boolean> f)
Returns the first elements of the head of this stream that match the given predicate function.

Parameters:
f - The predicate function to apply on this stream until it finds an element that does not hold, or the stream is exhausted.
Returns:
The first elements of the head of this stream that match the given predicate function.

dropWhile

public Stream<A> dropWhile(F<A,Boolean> f)
Removes elements from the head of this stream that do not match the given predicate function until an element is found that does match or the stream is exhausted.

Parameters:
f - The predicate function to apply through this stream.
Returns:
The stream whose first element does not match the given predicate function.

reverse

public Stream<A> reverse()
Reverse this stream in constant stack space.

Returns:
A new stream that is the reverse of this one.

length

public int length()
The length of this stream. This function will not terminate for an infinite stream.

Returns:
The length of this stream.

index

public A index(int i)
Returns the element at the given index if it exists, fails otherwise.

Parameters:
i - The index at which to get the element to return.
Returns:
The element at the given index if it exists, fails otherwise.

forall

public boolean forall(F<A,Boolean> f)
Returns true if the predicate holds for all of the elements of this stream, false otherwise (true for the empty stream).

Parameters:
f - the predicate function to test on each element of this stream.
Returns:
true if the predicate holds for all of the elements of this stream, false otherwise.

exists

public boolean exists(F<A,Boolean> f)
Returns true if the predicate holds for at least one of the elements of this stream, false otherwise (false for the empty stream).

Parameters:
f - The predicate function to test on the elements of this stream.
Returns:
true if the predicate holds for at least one of the elements of this stream.

find

public Option<A> find(F<A,Boolean> f)
Finds the first occurrence of an element that matches the given predicate or no value if no elements match.

Parameters:
f - The predicate function to test on elements of this stream.
Returns:
The first occurrence of an element that matches the given predicate or no value if no elements match.

cobind

public <B> Stream<B> cobind(F<Stream<A>,B> k)
Binds the given function across the stream of tails of this stream (Comonad pattern).

Parameters:
k - A function to bind across this stream and its tails.
Returns:
a new stream of the results of applying the given function to this stream and its tails.

tails

public Stream<Stream<A>> tails()
Returns a stream of the tails of this stream. A stream is considered to be a tail of itself in this context.

Returns:
a stream of the tails of this stream, starting with the stream itself.

sequenceW

public <B> Stream<B> sequenceW(Stream<F<Stream<A>,B>> fs)
Applies a stream of comonadic functions to this stream, returning a stream of values.

Parameters:
fs - A stream of comonadic functions to apply to this stream.
Returns:
A new stream of the results of applying the stream of functions to this stream.

toFunction

public F<Integer,A> toFunction()
Converts this stream to a function of natural numbers.

Returns:
A function from natural numbers to values with the corresponding position in this stream.

fromFunction

public static <A> Stream<A> fromFunction(F<Natural,A> f)
Converts a function of natural numbers to a stream.

Parameters:
f - The function to convert to a stream.
Returns:
A new stream of the results of the given function applied to the natural numbers, starting at 0.

fromFunction

public static <A,B> Stream<A> fromFunction(Enumerator<B> e,
                                           F<B,A> f,
                                           B i)
Converts a function of an enumerable type to a stream of the results of that function, starting at the given index.

Parameters:
e - An enumerator for the domain of the function.
f - The function to convert to a stream.
i - The index into the function at which to begin the stream.
Returns:
A new stream of the results of the given function applied to the values of the given enumerator, starting at the given value.

unzip

public static <A,B> P2<Stream<A>,Stream<B>> unzip(Stream<P2<A,B>> xs)
Transforms a stream of pairs into a stream of first components and a stream of second components.

Parameters:
xs - The stream of pairs to transform.
Returns:
A stream of first components and a stream of second components.

zipWith

public static <A,B,C> F<Stream<A>,F<Stream<B>,F<F<A,F<B,C>>,Stream<C>>>> zipWith()
A first-class version of the zipWith function.

Returns:
a function that zips two given streams with a given function.

cons

public static <A> F<A,F<P1<Stream<A>>,Stream<A>>> cons()
Returns a function that prepends (cons) an element to a stream to produce a new stream.

Returns:
A function that prepends (cons) an element to a stream to produce a new stream.

cons_

public static <A> F<A,F<Stream<A>,Stream<A>>> cons_()
Returns a function that prepends (cons) an element to a stream to produce a new stream.

Returns:
A function that prepends (cons) an element to a stream to produce a new stream.

nil

public static <A> Stream<A> nil()
Returns an empty stream.

Returns:
An empty stream.

nil_

public static <A> P1<Stream<A>> nil_()
Returns an empty stream.

Returns:
An empty stream.

isEmpty_

public static <A> F<Stream<A>,Boolean> isEmpty_()
Returns a function that determines whether a given stream is empty.

Returns:
A function that determines whether a given stream is empty.

isNotEmpty_

public static <A> F<Stream<A>,Boolean> isNotEmpty_()
Returns a function that determines whether a given stream is not empty.

Returns:
A function that determines whether a given stream is not empty.

single

public static <A> Stream<A> single(A a)
Returns a stream of one element containing the given value.

Parameters:
a - The value for the head of the returned stream.
Returns:
A stream of one element containing the given value.

single

public static <A> F<A,Stream<A>> single()
Returns a function that yields a stream containing its argument.

Returns:
a function that yields a stream containing its argument.

cons

public static <A> Stream<A> cons(A head,
                                 P1<Stream<A>> tail)
Prepends the given head element to the given tail element to produce a new stream.

Parameters:
head - The element to prepend.
tail - The stream to prepend to.
Returns:
The stream with the given element prepended.

join

public static <A> Stream<A> join(Stream<Stream<A>> o)
Joins the given stream of streams using a bind operation.

Parameters:
o - The stream of streams to join.
Returns:
A new stream that is the join of the given streams.

join

public static <A> F<Stream<Stream<A>>,Stream<A>> join()
A first-class version of join

Returns:
A function that joins a stream of streams using a bind operation.

unfold

public static <A,B> Stream<A> unfold(F<B,Option<P2<A,B>>> f,
                                     B b)
Unfolds across the given function starting at the given value to produce a stream.

Parameters:
f - The function to unfold across.
b - The start value to begin the unfold.
Returns:
A new stream that is a result of unfolding until the function does not produce a value.

iterableStream

public static <A> Stream<A> iterableStream(Iterable<A> i)
Takes the given iterable to a stream.

Parameters:
i - The iterable to take to a stream.
Returns:
A stream from the given iterable.

repeat

public static <A> Stream<A> repeat(A a)
Returns an infinite-length stream of the given element.

Parameters:
a - The element to repeat infinitely.
Returns:
An infinite-length stream of the given element.

cycle

public static <A> Stream<A> cycle(Stream<A> as)
Returns an infinite-length stream of the given elements cycling. Fails on the empty stream.

Parameters:
as - The elements to cycle infinitely. This must not be empty.
Returns:
An infinite-length stream of the given elements cycling.

iterate

public static <A> Stream<A> iterate(F<A,A> f,
                                    A a)
Returns a stream constructed by applying the given iteration function starting at the given value.

Parameters:
f - The iteration function.
a - The value to begin iterating from.
Returns:
A stream constructed by applying the given iteration function starting at the given value.

iterate

public static <A> F<F<A,A>,F<A,Stream<A>>> iterate()
A first-class version of the iterate function.

Returns:
A function that returns a stream constructed by applying a given iteration function starting at a given value.

Copyright Tony Morris 2008

This software is released under an open source BSD licence.