Copyright Workingmouse Pty. Ltd. 2007, 2008

This software is released under an open source BSD licence.

fj.data
Class IterableW<A>

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

public final class IterableW<A>
extends Object
implements Iterable<A>

A wrapper for Iterable that equips it with some useful functions.


Method Summary
<B> IterableW<B>
apply(Iterable<F<A,B>> f)
          Performs function application within an iterable (applicative functor pattern).
static
<A,B> F<F<A,B>,F<A,IterableW<B>>>
arrow()
          Provides a transformation from a function to a Iterable-valued function that is equivalent to it.
static
<A,B,T extends Iterable<B>>
F<IterableW<A>,F<F<A,T>,IterableW<B>>>
bind()
          The first-class bind function over Iterable.
<B,T extends Iterable<B>>
IterableW<B>
bind(F<A,T> f)
          Binds the given function across the wrapped Iterable with a final join.
static
<A,B,C> IterableW<C>
bind(Iterable<A> a, Iterable<B> b, F<A,F<B,C>> f)
          Binds the given function to the values in the given iterables with a final join.
<B> B
foldLeft(F<B,F<A,B>> f, B z)
          The catamorphism for Iterables, implemented as a left fold.
<B> B
foldRight(F2<A,B,B> f, B z)
          The catamorphism for Iterables, implemented as a right fold.
static
<A> IterableW<A>
iterable(A a)
          Returns an Iterable that completely preserves the argument.
static
<A,B> F<A,IterableW<B>>
iterable(F<A,B> f)
          Wraps a given function's return value in a Iterable.
 Iterator<A> iterator()
          Returns an iterator for this iterable.
static
<A,T extends Iterable<A>>
F<Iterable<T>,IterableW<A>>
join()
          Returns a function that joins an Iterable of Iterables into a single Iterable.
static
<A,T extends Iterable<A>>
IterableW<A>
join(Iterable<T> as)
          Joins an Iterable of Iterables into a single Iterable.
static
<A,B,C> F<Iterable<A>,F<Iterable<B>,IterableW<C>>>
liftM2(F<A,F<B,C>> f)
          Promotes a function of arity-2 to a function on iterables.
static
<A,B> F<F<A,B>,F<IterableW<A>,IterableW<B>>>
map()
          Returns a function that promotes any function so that it operates on Iterables.
<B> IterableW<B>
map(F<A,B> f)
          Maps a given function across the wrapped Iterable.
static
<A,T extends Iterable<A>>
IterableW<IterableW<A>>
sequence(Iterable<T> as)
          Performs a bind across each element of all iterables of an iterable, collecting the values in an iterable.
static
<A,T extends Iterable<A>>
F<T,IterableW<A>>
wrap()
          Provides a function that wraps the given iterable.
static
<A> IterableW<A>
wrap(Iterable<A> a)
          Wraps the given iterable.
<B> IterableW<B>
zapp(Iterable<F<A,B>> fs)
          Zips this iterable with the given iterable of functions, applying each function in turn to the corresponding element in this iterable to produce a new iterable.
<B> Iterable<P2<A,B>>
zip(Iterable<B> bs)
          Zips this iterable with the given iterable to produce a iterable of pairs.
 Iterable<P2<A,Integer>> zipIndex()
          Zips this iterable with the index of its element as a pair.
<B,C> Iterable<C>
zipWith(Iterable<B> bs, F<A,F<B,C>> f)
          Zips this iterable with the given iterable using the given function to produce a new iterable.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

wrap

public static <A> IterableW<A> wrap(Iterable<A> a)
Wraps the given iterable.

Parameters:
a - The iterable to wrap.
Returns:
An iterable equipped with some useful functions.

wrap

public static <A,T extends Iterable<A>> F<T,IterableW<A>> wrap()
Provides a function that wraps the given iterable.

Returns:
A function that returns the given iterable, wrapped.

iterable

public static <A> IterableW<A> iterable(A a)
Returns an Iterable that completely preserves the argument. The unit function for Iterables.

Parameters:
a - A value to preserve in an Iterable.
Returns:
An Iterable that yields the argument when iterated over.

iterable

public static <A,B> F<A,IterableW<B>> iterable(F<A,B> f)
Wraps a given function's return value in a Iterable. The Kleisli arrow for Iterables.

Parameters:
f - The function whose return value to wrap in a Iterable.
Returns:
The equivalent function whose return value is iterable.

arrow

public static <A,B> F<F<A,B>,F<A,IterableW<B>>> arrow()
Provides a transformation from a function to a Iterable-valued function that is equivalent to it. The first-class Kleisli arrow for Iterables.

Returns:
A transformation from a function to the equivalent Iterable-valued function.

bind

public <B,T extends Iterable<B>> IterableW<B> bind(F<A,T> f)
Binds the given function across the wrapped Iterable with a final join.

Parameters:
f - A function to bind across the Iterable.
Returns:
an iterable result of binding the given function over the wrapped Iterable.

apply

public <B> IterableW<B> apply(Iterable<F<A,B>> f)
Performs function application within an iterable (applicative functor pattern).

Parameters:
f - The iterable function to apply.
Returns:
A new iterable after applying the given iterable function to the wrapped iterable.

bind

public static <A,B,C> IterableW<C> bind(Iterable<A> a,
                                        Iterable<B> b,
                                        F<A,F<B,C>> f)
Binds the given function to the values in the given iterables with a final join.

Parameters:
a - A given iterable to bind the given function with.
b - A given iterable to bind the given function with.
f - The function to apply to the values in the given iterables.
Returns:
A new iterable after performing the map, then final join.

liftM2

public static <A,B,C> F<Iterable<A>,F<Iterable<B>,IterableW<C>>> liftM2(F<A,F<B,C>> f)
Promotes a function of arity-2 to a function on iterables.

Parameters:
f - The function to promote.
Returns:
A function of arity-2 promoted to map over iterables.

sequence

public static <A,T extends Iterable<A>> IterableW<IterableW<A>> sequence(Iterable<T> as)
Performs a bind across each element of all iterables of an iterable, collecting the values in an iterable. This implementation is strict and requires O(n) stack space.

Parameters:
as - The iterable of iterables to transform.
Returns:
A iterable of iterables containing the results of the bind operations across all given iterables.

bind

public static <A,B,T extends Iterable<B>> F<IterableW<A>,F<F<A,T>,IterableW<B>>> bind()
The first-class bind function over Iterable. Returns a function that binds a given function across a given iterable.

Returns:
a function that binds a given function across a given iterable.

join

public static <A,T extends Iterable<A>> IterableW<A> join(Iterable<T> as)
Joins an Iterable of Iterables into a single Iterable.

Parameters:
as - An Iterable of Iterables to join.
Returns:
the joined Iterable.

join

public static <A,T extends Iterable<A>> F<Iterable<T>,IterableW<A>> join()
Returns a function that joins an Iterable of Iterables into a single Iterable.

Returns:
a function that joins an Iterable of Iterables into a single Iterable.

map

public <B> IterableW<B> map(F<A,B> f)
Maps a given function across the wrapped Iterable.

Parameters:
f - A function to map across the wrapped Iterable.
Returns:
An Iterable of the results of mapping the given function across the wrapped Iterable.

map

public static <A,B> F<F<A,B>,F<IterableW<A>,IterableW<B>>> map()
Returns a function that promotes any function so that it operates on Iterables.

Returns:
a function that promotes any function so that it operates on Iterables.

foldLeft

public <B> B foldLeft(F<B,F<A,B>> f,
                      B z)
The catamorphism for Iterables, implemented as a left fold.

Parameters:
f - The function with which to fold the wrapped iterable.
z - The base case value of the destination type, applied first (leftmost) to the fold.
Returns:
The result of the catamorphism.

foldRight

public <B> B foldRight(F2<A,B,B> f,
                       B z)
The catamorphism for Iterables, implemented as a right fold.

Parameters:
f - The function with which to fold the wrapped iterable.
z - The base case value of the destination type, applied last (rightmost) to the fold.
Returns:
The result of the catamorphism.

iterator

public Iterator<A> iterator()
Returns an iterator for this iterable.

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

zapp

public <B> IterableW<B> zapp(Iterable<F<A,B>> fs)
Zips this iterable with the given iterable of functions, applying each function in turn to the corresponding element in this iterable to produce a new iterable. The iteration is normalised so that it ends when one of the iterators is exhausted.

Parameters:
fs - The iterable of functions to apply to this iterable.
Returns:
A new iterable with the results of applying the functions to this iterable.

zipWith

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

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

zip

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

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

zipIndex

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

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

Copyright Workingmouse Pty. Ltd. 2007, 2008

This software is released under an open source BSD licence.