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 Array<A>

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

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

Provides an interface to arrays.


Nested Class Summary
 class Array.ImmutableProjection<A>
          Projects an array by providing only operations which do not mutate.
 
Method Summary
 Array<A> append(Array<A> aas)
          Appends the given array to this array.
<B> Array<B>
apply(Array<F<A,B>> lf)
          Performs function application within an array (applicative functor pattern).
 Object[] array()
          Returns a copy of the underlying primitive array.
static
<A> Array<A>
array(A... a)
          Constructs an array from the given elements.
 A[] array(Class<A[]> c)
          Returns a copy of the underlying primitive array.
<B,C> Array<C>
bind(Array<B> sb, F<A,F<B,C>> f)
          Binds the given function across each element of this array and the given array with a final join.
<B,C> Array<C>
bind(Array<B> sb, F2<A,B,C> f)
          Binds the given function across each element of this array and the given array with a final join.
<B> Array<B>
bind(F<A,Array<B>> f)
          Binds the given function across each element of this array with a final join.
static
<A> Array<A>
empty()
          Returns an empty array.
 boolean exists(F<A,Boolean> f)
          Returns true if the predicate holds for at least one of the elements of this array, false otherwise (false for the empty array).
 Array<A> filter(F<A,Boolean> f)
          Filters elements from this array 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 array.
<B> B
foldLeft(F2<B,A,B> f, B b)
          Performs a left-fold reduction across this array.
<B> B
foldRight(F<A,F<B,B>> f, B b)
          Performs a right-fold reduction across this array.
<B> B
foldRight(F2<A,B,B> f, B b)
          Performs a right-fold reduction across this array.
 boolean forall(F<A,Boolean> f)
          Returns true if the predicate holds for all of the elements of this array, false otherwise (true for the empty array).
 void foreach(Effect<A> f)
          Performs a side-effect for each element of this array.
 Unit foreach(F<A,Unit> f)
          Performs a side-effect for each element of this array.
 A get(int index)
          Returns the element at the given index if it exists, fails otherwise.
 Array.ImmutableProjection<A> immutable()
           
 boolean isEmpty()
          Returns true is this array is empty, false otherwise.
 boolean isNotEmpty()
          Returns false is this array is empty, true otherwise.
static
<A> Array<A>
iterableArray(Iterable<A> i)
          Takes the given iterable to an array.
 Iterator<A> iterator()
          Returns an iterator for this array.
static
<A> F<Array<Array<A>>,Array<A>>
join()
          A first-class version of join
static
<A> Array<A>
join(Array<Array<A>> o)
          Joins the given array of arrays using a bind operation.
 int length()
          Returns the length of this array.
static
<A,B> F<F<A,B>,F<Array<A>,Array<B>>>
map()
          First-class map function for Arrays.
<B> Array<B>
map(F<A,B> f)
          Maps the given function across this array.
static Array<Integer> range(int from, int to)
          Returns an array of integers from the given from value (inclusive) to the given to value (exclusive).
 Array<A> reverse()
          Reverse this array in constant stack space.
<B> Array<B>
sequence(Array<B> bs)
          Performs a bind across each array element, but ignores the element value each time.
 Unit set(int index, A a)
          Sets the element at the given index to the given value.
static
<A> Array<A>
single(A a)
          Constructs a singleton array.
 Collection<A> toCollection()
          Projects an immutable collection of this array.
<X> Either<X,A>
toEither(P1<X> x)
          Returns an either projection of this array; the given argument in Left if empty, or the first element in Right.
 List<A> toList()
          Returns a list projection of this array.
 Option<A> toOption()
          Returns an option projection of this array; None if empty, or the first element in Some.
 Stream<A> toStream()
          Returns a stream projection of this array.
static
<A,B> P2<Array<A>,Array<B>>
unzip(Array<P2<A,B>> xs)
          Transforms an array of pairs into an array of first components and an array of second components.
static
<A> F<A[],Array<A>>
wrap()
          First-class wrapper function for arrays.
<B> Array<P2<A,B>>
zip(Array<B> bs)
          Zips this array with the given array to produce an array of pairs.
 Array<P2<A,Integer>> zipIndex()
          Zips this array with the index of its element as a pair.
<B,C> Array<C>
zipWith(Array<B> bs, F<A,F<B,C>> f)
          Zips this array with the given array using the given function to produce a new array.
<B,C> Array<C>
zipWith(Array<B> bs, F2<A,B,C> f)
          Zips this array with the given array using the given function to produce a new array.
 
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 array. This method exists to permit the use in a for-each loop.

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

get

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

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

set

public Unit set(int index,
                A a)
Sets the element at the given index to the given value.

Parameters:
index - The index at which to set the given value.
a - The value to set at the given index.
Returns:
The unit value.

length

public int length()
Returns the length of this array.

Returns:
The length of this array.

immutable

public Array.ImmutableProjection<A> immutable()

isEmpty

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

Returns:
true is this array is empty, false otherwise.

isNotEmpty

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

Returns:
false is this array is empty, true otherwise.

array

public A[] array(Class<A[]> c)
Returns a copy of the underlying primitive array.

Parameters:
c - A class for the returned array.
Returns:
A copy of the underlying primitive array.

array

public Object[] array()
Returns a copy of the underlying primitive array.

Returns:
A copy of the underlying primitive array;

toOption

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

Returns:
An option projection of this array.

toEither

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

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

toList

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

Returns:
A list projection of this array.

toStream

public Stream<A> toStream()
Returns a stream projection of this array.

Returns:
A stream projection of this array.

map

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

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

filter

public Array<A> filter(F<A,Boolean> f)
Filters elements from this array 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 array whose elements all match the given predicate.

foreach

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

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 array.

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

foldRight

public <B> B foldRight(F<A,F<B,B>> f,
                       B b)
Performs a right-fold reduction across this array. This function runs in constant stack space.

Parameters:
f - The function to apply on each element of the array.
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,B,B> f,
                       B b)
Performs a right-fold reduction across this array. This function runs in constant stack space.

Parameters:
f - The function to apply on each element of the array.
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 array. This function runs in constant space.

Parameters:
f - The function to apply on each element of the array.
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 array. This function runs in constant space.

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

bind

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

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

sequence

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

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

bind

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

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

bind

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

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

apply

public <B> Array<B> apply(Array<F<A,B>> lf)
Performs function application within an array (applicative functor pattern).

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

reverse

public Array<A> reverse()
Reverse this array in constant stack space.

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

append

public Array<A> append(Array<A> aas)
Appends the given array to this array.

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

empty

public static <A> Array<A> empty()
Returns an empty array.

Returns:
An empty array.

array

public static <A> Array<A> array(A... a)
Constructs an array from the given elements.

Parameters:
a - The elements to construct the array with.
Returns:
A new array of the given elements.

single

public static <A> Array<A> single(A a)
Constructs a singleton array.

Parameters:
a - The element to put in the array.
Returns:
An array with the given single element.

wrap

public static <A> F<A[],Array<A>> wrap()
First-class wrapper function for arrays.

Returns:
A function that wraps a given array.

map

public static <A,B> F<F<A,B>,F<Array<A>,Array<B>>> map()
First-class map function for Arrays.

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

join

public static <A> Array<A> join(Array<Array<A>> o)
Joins the given array of arrays using a bind operation.

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

join

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

Returns:
A function that joins a array of arrays using a bind operation.

forall

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

Parameters:
f - the predicate function to test on each element of this array.
Returns:
true if the predicate holds for all of the elements of this array, 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 array, false otherwise (false for the empty array).

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

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 array.
Returns:
The first occurrence of an element that matches the given predicate or no value if no elements match.

range

public static Array<Integer> range(int from,
                                   int to)
Returns an array of integers from the given from value (inclusive) to the given to value (exclusive).

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

zipWith

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

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

zipWith

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

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

zip

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

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

zipIndex

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

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

toCollection

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

Returns:
An immutable collection of this array.

iterableArray

public static <A> Array<A> iterableArray(Iterable<A> i)
Takes the given iterable to an array.

Parameters:
i - The iterable to take to an array.
Returns:
An array from the given iterable.

unzip

public static <A,B> P2<Array<A>,Array<B>> unzip(Array<P2<A,B>> xs)
Transforms an array of pairs into an array of first components and an array of second components.

Parameters:
xs - The array of pairs to transform.
Returns:
An array of first components and an array of second components.

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.