info.javelot.functionalj
Class Functions

java.lang.Object
  info.javelot.functionalj.Functions

public final class Functions
extends Object

The Functions class contains static methods that use functions to perform various computations, which makes it possible to use certain functional programming patterns. These patterns include:

• Mapping
• Folding
• Scanning

Note about Folding

Folding consists of using a function that requires two parameters, and applying it to a collection of elements, each time using the result of the previous function call as the first parameter to the next function call. The result of the last function call is the overall result of the fold.

Folding can be performed from the left or from the right.

Folding a collection from the left using a function f, a starting parameter p, and a collection of elements [e1, e2, ..., en] is equal to:

f(f(f(f(p, e1), e2), ...), en)

Folding a collection from the right using a function f, a starting parameter p, and a collection of elements [e1, e2, ..., en] is equal to:

f(e1, f(e2, f(..., f(en, p))))

Note about Scanning

Scanning is similar to folding except that scanning returns a list of successive reduced values, from the left or from the right.

Thus, folding from the left takes the last element of the list that results from scanning from the left; folding from the right takes the first element of the list that results from scanning from the right.

Thanks to Paul Field for his suggestions on improving performance.

Author:

Copyright © 2006 Frederic Daoud

Method Summary

static <P> boolean	all(Function1<Boolean,P> p_function1, Collection<? extends P> p_coll) Determines if all of the elements of the collection satisfy the condition represented by the given function.
static <P> boolean	all(Function1<Boolean,P> p_function1, P[] p_array) Version of all(Function1,Collection) that accepts an array.
static boolean	and(boolean[] p_array) Version of and(Collection) that accepts an array.
static boolean	and(Boolean[] p_array) Version of and(Collection) that accepts an array.
static boolean	and(Collection<Boolean> p_coll) Returns the result of &&ing the Boolean values in the given collection.
static <P> boolean	any(Function1<Boolean,P> p_function1, Collection<? extends P> p_coll) Determines whether any of the elements of the collection satisfy the condition represented by the given function.
static <P> boolean	any(Function1<Boolean,P> p_function1, P[] p_array) Version of any(Function1,Collection) that accepts an array.
static <P> List<P>	filter(Function1<Boolean,P> p_filter, Collection<? extends P> p_coll) Filters a collection of items according to a filter function, which accepts one parameter of the same type as the items, and returns a Boolean value indicating whether or not the item satisfies the filter condition.
static <P> List<P>	filter(Function1<Boolean,P> p_filter, P[] p_array) Version of filter(Function1, Collection) which accepts an array.
static <P> List<P>	filterNot(Function1<Boolean,P> p_filter, Collection<? extends P> p_coll) Same as filter(Function1,Collection), except that the elements that do not satisfy the filter condition are returned.
static <P> List<P>	filterNot(Function1<Boolean,P> p_filter, P[] p_array) Version of filterNot(Function1, Collection) which accepts an array.
static <R,P> R	foldl(Function2<R,R,P> p_function2, R p_start, Collection<? extends P> p_coll) Folds a collection from the left using the given function and starting parameter.
static <R,P> R	foldl(Function2<R,R,P> p_function2, R p_start, P[] p_array) Version of foldl(Function2,Object,Collection) that accepts an array.
static <R> R	foldl1(Function2<R,R,R> p_function2, Collection<? extends R> p_coll) Folds a collection from the left using the given function.
static <R> R	foldl1(Function2<R,R,R> p_function2, R[] p_array) Version of foldl1(Function2,Collection) that accepts an array.
static <R,P> R	foldr(Function2<R,P,R> p_function2, R p_start, Collection<? extends P> p_coll) Folds a collection from the right using the given function and starting parameter.
static <R,P> R	foldr(Function2<R,P,R> p_function2, R p_start, P[] p_array) Version of foldr(Function2,Object,Collection) that accepts an array.
static <R> R	foldr1(Function2<R,R,R> p_function2, Collection<? extends R> p_coll) Folds a collection from the right using the given function.
static <R> R	foldr1(Function2<R,R,R> p_function2, R[] p_array) Version of foldr1(Function2,Collection) that accepts an array.
static <R,P> List<R>	map(Function1<R,P> p_function1, Collection<? extends P> p_coll) Maps a function to a collection of parameters, by calling the function with each element of the collection in turn as a parameter, and returning a list of the results.
static <R,P> List<R>	map(Function1<R,P> p_function1, P... p_array) Version of map(Function1, Collection) which accepts an array.
static boolean	or(boolean[] p_array) Version of or(Collection) that accepts an array.
static boolean	or(Boolean[] p_array) Version of or(Collection) that accepts an array.
static boolean	or(Collection<Boolean> p_coll) Returns the result of ||ing the Boolean values in the given collection.
static <R,P> List<R>	scanl(Function2<R,R,P> p_function2, R p_start, Collection<? extends P> p_coll) Scans a collection to return successive reduced values from the left.
static <R,P> List<R>	scanl(Function2<R,R,P> p_function2, R p_start, P[] p_array) Version of scanl(Function2,Object,Collection) which accepts an array.
static <R> List<R>	scanl1(Function2<R,R,R> p_function2, Collection<? extends R> p_coll) Scans a collection to return successive reduced values from the left, using the first element of the collection as a starting parameter.
static <R> List<R>	scanl1(Function2<R,R,R> p_function2, R[] p_array) Version of scanl1(Function2,Collection) that accepts an array.
static <R,P> List<R>	scanr(Function2<R,P,R> p_function2, R p_start, Collection<? extends P> p_coll) Scans a collection to return successive reduced values from the right.
static <R,P> List<R>	scanr(Function2<R,P,R> p_function2, R p_start, P[] p_array) Version of scanr(Function2,Object,Collection) that accepts an array.
static <R> List<R>	scanr1(Function2<R,R,R> p_function2, Collection<? extends R> p_coll) Scans a collection to return successive reduced values from the right, using the first element of the collection as a starting parameter.
static <R> List<R>	scanr1(Function2<R,R,R> p_function2, R[] p_array) Version of scanr1(Function2,Collection) that accepts an array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

map

public static <R,P> List<R> map(Function1<R,P> p_function1,
                                Collection<? extends P> p_coll)
                   throws FunctionException

Maps a function to a collection of parameters, by calling the function with each element of the collection in turn as a parameter, and returning a list of the results.

Parameters:

p_function1 - the function to map.

p_coll - the collection of parameters on which to map the function.

Returns:

a list of the results of calling the function on each parameter of the collection. If the collection is null or empty, an empty list is returned.

Throws:

FunctionException - thrown if the function is null, or if one is thrown while using the function.

map

public static <R,P> List<R> map(Function1<R,P> p_function1,
                                P... p_array)

Version of map(Function1, Collection) which accepts an array.

See Also:

map(Function1, Collection).

filter

public static <P> List<P> filter(Function1<Boolean,P> p_filter,
                                 Collection<? extends P> p_coll)
                      throws FunctionException

Filters a collection of items according to a filter function, which accepts one parameter of the same type as the items, and returns a Boolean value indicating whether or not the item satisfies the filter condition.

Type Parameters:

P - the type of the items to be filtered.

Parameters:

p_filter - the filter function.

p_coll - the collection of items to be filtered.

Returns:

a list of the items for which the filter function returns true.

Throws:

FunctionException - thrown if an exception occurs while calling the filter function.

filter

public static <P> List<P> filter(Function1<Boolean,P> p_filter,
                                 P[] p_array)
                      throws FunctionException

Version of filter(Function1, Collection) which accepts an array.

Throws:

FunctionException

See Also:

filter(Function1, Collection).

filterNot

public static <P> List<P> filterNot(Function1<Boolean,P> p_filter,
                                    Collection<? extends P> p_coll)
                         throws FunctionException

Same as filter(Function1,Collection), except that the elements that do not satisfy the filter condition are returned.

Throws:

FunctionException

See Also:

filter(Function1,Collection)

filterNot

public static <P> List<P> filterNot(Function1<Boolean,P> p_filter,
                                    P[] p_array)
                         throws FunctionException

Version of filterNot(Function1, Collection) which accepts an array.

Throws:

FunctionException

See Also:

filterNot(Function1, Collection).

foldl

public static <R,P> R foldl(Function2<R,R,P> p_function2,
                            R p_start,
                            Collection<? extends P> p_coll)
               throws FunctionException

Folds a collection from the left using the given function and starting parameter. For more details about folding, see the class documentation above.

Parameters:

p_function2 - the function to use while folding.

p_start - the starting parameter to the function.

p_coll - the collection of elements to be folded.

Returns:

the result of folding the elements of the collection from the left with the given function and starting parameter.

Throws:

FunctionException - thrown if the function is null, or if an exception occurs while using the function.

foldl

public static <R,P> R foldl(Function2<R,R,P> p_function2,
                            R p_start,
                            P[] p_array)
               throws FunctionException

Version of foldl(Function2,Object,Collection) that accepts an array.

Throws:

FunctionException

See Also:

foldl(Function2,Object,Collection)

foldl1

public static <R> R foldl1(Function2<R,R,R> p_function2,
                           Collection<? extends R> p_coll)
                throws FunctionException

Folds a collection from the left using the given function. The first element of the collection is used as a starting parameter. For more details about folding, see the class documentation above.

Parameters:

p_function2 - the function to use while folding.

p_coll - the collection of elements to be folded.

Returns:

the result of folding the elements of the collection from the left with the given function and starting parameter.

Throws:

FunctionException - thrown if the collection is null or empty.

See Also:

foldl(Function2, Object, Collection)

foldl1

public static <R> R foldl1(Function2<R,R,R> p_function2,
                           R[] p_array)
                throws FunctionException

Version of foldl1(Function2,Collection) that accepts an array.

Throws:

FunctionException

See Also:

foldl1(Function2,Collection)

scanl

public static <R,P> List<R> scanl(Function2<R,R,P> p_function2,
                                  R p_start,
                                  Collection<? extends P> p_coll)
                     throws FunctionException

Scans a collection to return successive reduced values from the left. For more details about scanning, see the class documentation above.

Parameters:

p_function2 - the function used for scanning.

p_start - the starting parameter to the function.

p_coll - the collection of elements to be scanned.

Returns:

successive reduced values from the left.

Throws:

FunctionException - thrown if the function is null or if an exception occurs while calling the function.

scanl

public static <R,P> List<R> scanl(Function2<R,R,P> p_function2,
                                  R p_start,
                                  P[] p_array)
                     throws FunctionException

Version of scanl(Function2,Object,Collection) which accepts an array.

Throws:

FunctionException

See Also:

scanl(Function2,Object,Collection)

scanl1

public static <R> List<R> scanl1(Function2<R,R,R> p_function2,
                                 Collection<? extends R> p_coll)
                      throws FunctionException

Scans a collection to return successive reduced values from the left, using the first element of the collection as a starting parameter.

Throws:

FunctionException

See Also:

scanl(Function2, Object, Collection).

scanl1

public static <R> List<R> scanl1(Function2<R,R,R> p_function2,
                                 R[] p_array)
                      throws FunctionException

Version of scanl1(Function2,Collection) that accepts an array.

Throws:

FunctionException

See Also:

scanl1(Function2,Collection)

foldr

public static <R,P> R foldr(Function2<R,P,R> p_function2,
                            R p_start,
                            Collection<? extends P> p_coll)
               throws FunctionException

Folds a collection from the right using the given function and starting parameter. For more details about folding, see the class documentation above.

Parameters:

p_function2 - the function to use while folding.

p_start - the starting parameter to the function.

p_coll - the collection of elements to be folded.

Returns:

the result of folding the elements of the collection from the right with the given function and starting parameter.

Throws:

FunctionException - thrown if the function is null, or if an exception occurs while using the function.

foldr

public static <R,P> R foldr(Function2<R,P,R> p_function2,
                            R p_start,
                            P[] p_array)
               throws FunctionException

Version of foldr(Function2,Object,Collection) that accepts an array.

Throws:

FunctionException

See Also:

foldr(Function2,Object,Collection).

foldr1

public static <R> R foldr1(Function2<R,R,R> p_function2,
                           Collection<? extends R> p_coll)
                throws FunctionException

Folds a collection from the right using the given function. The first element of the list is used as a starting parameter. For more details about folding, see the class documentation above.

Parameters:

p_function2 - the function to use while folding.

p_coll - the collection of elements to be folded.

Returns:

the result of folding the elements of the collection from the right with the given function and starting parameter.

Throws:

FunctionException - thrown if the list is null or empty.

See Also:

foldr(Function2,Object,Collection)

foldr1

public static <R> R foldr1(Function2<R,R,R> p_function2,
                           R[] p_array)
                throws FunctionException

Version of foldr1(Function2,Collection) that accepts an array.

Throws:

FunctionException

See Also:

foldr1(Function2,Collection).

scanr

public static <R,P> List<R> scanr(Function2<R,P,R> p_function2,
                                  R p_start,
                                  Collection<? extends P> p_coll)
                     throws FunctionException

Scans a collection to return successive reduced values from the right. For more details about scanning, see the class documentation above.

Parameters:

p_function2 - the function used for scanning.

p_start - the starting parameter to the function.

p_coll - the collection of elements to be scanned.

Returns:

successive reduced values from the right.

Throws:

FunctionException - thrown if the function is null.

scanr

public static <R,P> List<R> scanr(Function2<R,P,R> p_function2,
                                  R p_start,
                                  P[] p_array)
                     throws FunctionException

Version of scanr(Function2,Object,Collection) that accepts an array.

Throws:

FunctionException

See Also:

scanr(Function2,Object,Collection).

scanr1

public static <R> List<R> scanr1(Function2<R,R,R> p_function2,
                                 Collection<? extends R> p_coll)
                      throws FunctionException

Scans a collection to return successive reduced values from the right, using the first element of the collection as a starting parameter.

Throws:

FunctionException

See Also:

scanr(Function2,Object,Collection).

scanr1

public static <R> List<R> scanr1(Function2<R,R,R> p_function2,
                                 R[] p_array)
                      throws FunctionException

Version of scanr1(Function2,Collection) that accepts an array.

Throws:

FunctionException

See Also:

scanr1(Function2,Collection).

and

public static boolean and(Collection<Boolean> p_coll)
                   throws FunctionException

Returns the result of &&ing the Boolean values in the given collection. Thus if at least one value is false, the result will be false.

Parameters:

p_coll - the collection of Boolean values to be &&ed.

Returns:

true if all the values of the collection are true; false otherwise.

Throws:

FunctionException - thrown if not all elements of the collection are of Boolean type.

and

public static boolean and(Boolean[] p_array)
                   throws FunctionException

Version of and(Collection) that accepts an array.

Throws:

FunctionException

See Also:

and(Collection).

and

public static boolean and(boolean[] p_array)
                   throws FunctionException

Version of and(Collection) that accepts an array.

Throws:

FunctionException

See Also:

and(Collection).

all

public static <P> boolean all(Function1<Boolean,P> p_function1,
                              Collection<? extends P> p_coll)
                   throws FunctionException

Determines if all of the elements of the collection satisfy the condition represented by the given function.

Parameters:

p_function1 - the function that represents the condition to be met.

p_coll - the collection of elements to be tested against the condition.

Returns:

true if all of the elements of the collection satisfy the condition; false otherwise.

Throws:

FunctionException

all

public static <P> boolean all(Function1<Boolean,P> p_function1,
                              P[] p_array)
                   throws FunctionException

Version of all(Function1,Collection) that accepts an array.

Throws:

FunctionException

See Also:

all(Function1,Collection).

or

public static boolean or(Collection<Boolean> p_coll)
                  throws FunctionException

Returns the result of ||ing the Boolean values in the given collection. Thus if at least one value is true, the result will be true.

Parameters:

p_coll - the collection of Boolean values to be ||ed.

Returns:

false if all the values of the collection are false; true otherwise.

Throws:

FunctionException

or

public static boolean or(Boolean[] p_array)
                  throws FunctionException

Version of or(Collection) that accepts an array.

Throws:

FunctionException

See Also:

or(Collection).

or

public static boolean or(boolean[] p_array)
                  throws FunctionException

Version of or(Collection) that accepts an array.

Throws:

FunctionException

See Also:

or(Collection).

any

public static <P> boolean any(Function1<Boolean,P> p_function1,
                              Collection<? extends P> p_coll)
                   throws FunctionException

Determines whether any of the elements of the collection satisfy the condition represented by the given function.

Parameters:

p_function1 - the function that represents the condition to be met.

p_coll - the collection of elements to be tested against the condition.

Returns:

true if at least one element of the collection satisfies the condition; false otherwise.

Throws:

FunctionException

any

public static <P> boolean any(Function1<Boolean,P> p_function1,
                              P[] p_array)
                   throws FunctionException

Version of any(Function1,Collection) that accepts an array.

Throws:

FunctionException

See Also:

any(Function1,Collection).