Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

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.


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).
static String asString(Stream<Character> cs)
          Returns a string from the given stream of characters.
static
<A,B> F<F<A,Stream<B>>,F<Stream<A>,Stream<B>>>
bind_()
          A first-class version of the bind function.
<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> Stream<C>
bind(Stream<B> sb, F2<A,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 substreams of this stream.
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.
static
<A,B> F<F<A,F<P1<B>,B>>,F<B,F<Stream<A>,B>>>
foldRight()
          A first-class version of the foldRight function.
<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.
static Stream<Character> fromString(String s)
          Returns a stream of characters from the given string.
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.
 Option<Integer> indexOf(F<A,Boolean> p)
          Returns the position of the first element matching the given predicate, if any.
 Stream<Stream<A>> inits()
          Returns a stream of all prefixes of this stream.
 Stream<A> interleave(Stream<A> as)
          Interleaves the given stream with this stream to produce a new stream.
 Stream<A> intersperse(A a)
          Intersperses the given value between each two elements of the 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.
static
<A> Stream<A>
iterateWhile(F<A,A> f, F<A,Boolean> p, A a)
          Creates a stream where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.
 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 by concatenation.
 A last()
          Get the last element of this stream.
 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.
<B,C> F<B,Stream<C>>
mapM(F<A,F<B,C>> f)
          Maps the given function of arity-2 across this stream and returns a function that applies all the resulting functions to a given argument.
 Stream<A> minus(Equal<A> eq, Stream<A> xs)
          Returns a new stream of all the items in this stream that do not appear in the given 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.
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, long to)
          Returns a stream of integers from the given from value (inclusive) to the given to value (exclusive).
 Stream<A> removeAll(F<A,Boolean> f)
          Filters elements from this stream by returning only elements which produce false when the given function is applied to them.
static
<A> Stream<A>
repeat(A a)
          Returns an infinite-length stream of the given element.
 Stream<A> replace(F<A,Boolean> p, A a)
          Returns a new stream resulting from replacing all elements that match the given predicate with 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.
static
<A,B> F<B,Stream<A>>
sequence(Stream<F<B,A>> fs)
          Turn a stream of functions into a function returning a stream.
<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(A a)
          Append the given element to this stream to product a new stream.
 Stream<A> snoc(P1<A> a)
          Append the given element to this stream to produce a new stream.
 Stream<A> sort(Ord<A> o)
          Sort this stream according to the given ordering.
 Stream<A> sort(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.
 P2<Stream<A>,Stream<A>> span(F<A,Boolean> p)
          Returns a tuple where the first element is the longest prefix of this stream that satisfies the given predicate and the second element is the remainder of the stream.
 P2<Stream<A>,Stream<A>> split(F<A,Boolean> p)
          Returns a tuple where the first element is the longest prefix of this stream that does not satisfy the given predicate and the second element is the remainder of the 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.
 Stream<Stream<A>> substreams()
          Returns a stream of all infixes of this stream.
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 suffixes 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> F<Stream<B>,Stream<C>>
zipWith(F<A,F<B,C>> f)
          Partially-applied version of zipWith.
<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.
<B,C> Stream<C>
zipWith(Stream<B> bs, F2<A,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.

intersperse

public Stream<A> intersperse(A a)
Intersperses the given value between each two elements of the stream.

Parameters:
a - The value to intersperse between values of the stream.
Returns:
A new stream with the given value between each two elements of the stream.

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.

minus

public Stream<A> minus(Equal<A> eq,
                       Stream<A> xs)
Returns a new stream of all the items in this stream that do not appear in the given stream.

Parameters:
eq - an equality for the items of the streams.
xs - a list to subtract from this stream.
Returns:
a stream of all the items in this stream that do not appear in the given stream.

removeAll

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

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

sequence

public static <A,B> F<B,Stream<A>> sequence(Stream<F<B,A>> fs)
Turn a stream of functions into a function returning a stream.

Parameters:
fs - The stream of functions to sequence into a single function that returns a stream.
Returns:
A function that, when given an argument, applies all the functions in the given stream to it and returns a stream of the results.

mapM

public <B,C> F<B,Stream<C>> mapM(F<A,F<B,C>> f)
Maps the given function of arity-2 across this stream and returns a function that applies all the resulting functions to a given argument.

Parameters:
f - A function of arity-2
Returns:
A function that, when given an argument, applies the given function to that argument and every element in this list.

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> Stream<C> bind(Stream<B> sb,
                            F2<A,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.

sort

public Stream<A> sort(Ord<A> o)
Sort this stream according to the given ordering.

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.

sort

public Stream<A> sort(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,
                                    long 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.

zipWith

public <B,C> Stream<C> zipWith(Stream<B> bs,
                               F2<A,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.

zipWith

public <B,C> F<Stream<B>,Stream<C>> zipWith(F<A,F<B,C>> f)
Partially-applied version of zipWith. Returns a function that zips a given stream with this stream using the given function.

Parameters:
f - The function to zip this stream and a given stream with.
Returns:
A function that zips a given stream with this stream using the given function.

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.

asString

public static String asString(Stream<Character> cs)
Returns a string from the given stream of characters. The inverse of this function is fromString(String).

Parameters:
cs - The stream of characters to produce the string from.
Returns:
A string from the given stream of characters.

fromString

public static Stream<Character> fromString(String s)
Returns a stream of characters from the given string. The inverse of this function is asString(Stream).

Parameters:
s - The string to produce the stream of characters from.
Returns:
A stream of characters from the given string.

snoc

public Stream<A> snoc(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.

snoc

public Stream<A> snoc(P1<A> a)
Append the given element to this stream to produce 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.

span

public P2<Stream<A>,Stream<A>> span(F<A,Boolean> p)
Returns a tuple where the first element is the longest prefix of this stream that satisfies the given predicate and the second element is the remainder of the stream.

Parameters:
p - A predicate to be satisfied by a prefix of this stream.
Returns:
A tuple where the first element is the longest prefix of this stream that satisfies the given predicate and the second element is the remainder of the stream.

replace

public Stream<A> replace(F<A,Boolean> p,
                         A a)
Returns a new stream resulting from replacing all elements that match the given predicate with the given element.

Parameters:
p - The predicate to match replaced elements.
a - The element with which to replace elements.
Returns:
A new stream resulting from replacing all elements that match the given predicate with the given element.

split

public P2<Stream<A>,Stream<A>> split(F<A,Boolean> p)
Returns a tuple where the first element is the longest prefix of this stream that does not satisfy the given predicate and the second element is the remainder of the stream.

Parameters:
p - A predicate not to be satisfied by a prefix of this stream.
Returns:
A tuple where the first element is the longest prefix of this stream that does not satisfy the given predicate and the second element is the remainder of the stream.

reverse

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

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

last

public A last()
Get the last element of this stream. Undefined for infinite streams.

Returns:
The last element in this stream, if there is 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 substreams of this stream.

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

tails

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

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

inits

public Stream<Stream<A>> inits()
Returns a stream of all prefixes of this stream. A stream is considered a prefix of itself in tnis context.

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

substreams

public Stream<Stream<A>> substreams()
Returns a stream of all infixes of this stream. A stream is considered to contain itself.

Returns:
a stream of the infixes of this stream.

indexOf

public Option<Integer> indexOf(F<A,Boolean> p)
Returns the position of the first element matching the given predicate, if any.

Parameters:
p - A predicate to match.
Returns:
the position of the first element matching the given predicate, if any.

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 by concatenation.

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.

iterateWhile

public static <A> Stream<A> iterateWhile(F<A,A> f,
                                         F<A,Boolean> p,
                                         A a)
Creates a stream where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.

Parameters:
f - The function to iterate with.
p - The predicate which must be true for the next item in order to continue the iteration.
a - The input to the first iteration.
Returns:
A stream where the first item is calculated by applying the function on the third argument, the second item by applying the function on the previous result and so on.

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.

bind_

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

Returns:
A function that binds a given function across a given stream, joining the resulting streams.

foldRight

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

Returns:
A function that folds a given stream with a given function.

Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

This software is released under an open source BSD licence.