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 boolean	all(Function1 p_function1, Collection p_coll) Determines if all of the elements of the collection satisfy the condition represented by the given function.
static boolean	all(Function1 p_function1, Object[] 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 p_coll) Returns the result of &&ing the Boolean values in the given collection.
static boolean	any(Function1 p_function1, Collection p_coll) Determines whether any of the elements of the collection satisfy the condition represented by the given function.
static boolean	any(Function1 p_function1, Object[] p_array) Version of any(Function1,Collection) that accepts an array.
static List	filter(Function1 p_filter, Collection 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 List	filter(Function1 p_filter, Object[] p_array) Version of filter(Function1, Collection) which accepts an array.
static List	filterNot(Function1 p_filter, Collection p_coll) Same as filter(Function1,Collection), except that the elements that do not satisfy the filter condition are returned.
static List	filterNot(Function1 p_filter, Object[] p_array) Version of filterNot(Function1, Collection) which accepts an array.
static Object	foldl(Function2 p_function2, Object p_start, Collection p_coll) Folds a collection from the left using the given function and starting parameter.
static Object	foldl(Function2 p_function2, Object p_start, Object[] p_array) Version of foldl(Function2,Object,Collection) that accepts an array.
static Object	foldl1(Function2 p_function2, Collection p_coll) Folds a collection from the left using the given function.
static Object	foldl1(Function2 p_function2, Object[] p_array) Version of foldl1(Function2,Collection) that accepts an array.
static Object	foldr(Function2 p_function2, Object p_start, Collection p_coll) Folds a collection from the right using the given function and starting parameter.
static Object	foldr(Function2 p_function2, Object p_start, Object[] p_array) Version of foldr(Function2,Object,Collection) that accepts an array.
static Object	foldr1(Function2 p_function2, Collection p_coll) Folds a collection from the right using the given function.
static Object	foldr1(Function2 p_function2, Object[] p_array) Version of foldr1(Function2,Collection) that accepts an array.
static List	map(Function1 p_function1, Collection 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 List	map(Function1 p_function1, Object[] 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 p_coll) Returns the result of ||ing the Boolean values in the given collection.
static List	scanl(Function2 p_function2, Object p_start, Collection p_coll) Scans a collection to return successive reduced values from the left.
static List	scanl(Function2 p_function2, Object p_start, Object[] p_array) Version of scanl(Function2,Object,Collection) which accepts an array.
static List	scanl1(Function2 p_function2, Collection 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 List	scanl1(Function2 p_function2, Object[] p_array) Version of scanl1(Function2,Collection) that accepts an array.
static List	scanr(Function2 p_function2, Object p_start, Collection p_coll) Scans a collection to return successive reduced values from the right.
static List	scanr(Function2 p_function2, Object p_start, Object[] p_array) Version of scanr(Function2,Object,Collection) that accepts an array.
static List	scanr1(Function2 p_function2, Collection 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 List	scanr1(Function2 p_function2, Object[] 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 List map(Function1 p_function1,
                       Collection 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 List map(Function1 p_function1,
                       Object[] p_array)

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

See Also:

map(Function1, Collection).

filter

public static List filter(Function1 p_filter,
                          Collection 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.

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 List filter(Function1 p_filter,
                          Object[] p_array)
                   throws FunctionException

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

Throws:

FunctionException

See Also:

filter(Function1, Collection).

filterNot

public static List filterNot(Function1 p_filter,
                             Collection 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 List filterNot(Function1 p_filter,
                             Object[] p_array)
                      throws FunctionException

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

Throws:

FunctionException

See Also:

filterNot(Function1, Collection).

foldl

public static Object foldl(Function2 p_function2,
                           Object p_start,
                           Collection 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 Object foldl(Function2 p_function2,
                           Object p_start,
                           Object[] 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 Object foldl1(Function2 p_function2,
                            Collection 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 Object foldl1(Function2 p_function2,
                            Object[] p_array)
                     throws FunctionException

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

Throws:

FunctionException

See Also:

foldl1(Function2,Collection)

scanl

public static List scanl(Function2 p_function2,
                         Object p_start,
                         Collection 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 List scanl(Function2 p_function2,
                         Object p_start,
                         Object[] 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 List scanl1(Function2 p_function2,
                          Collection 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 List scanl1(Function2 p_function2,
                          Object[] p_array)
                   throws FunctionException

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

Throws:

FunctionException

See Also:

scanl1(Function2,Collection)

foldr

public static Object foldr(Function2 p_function2,
                           Object p_start,
                           Collection 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 Object foldr(Function2 p_function2,
                           Object p_start,
                           Object[] 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 Object foldr1(Function2 p_function2,
                            Collection 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 Object foldr1(Function2 p_function2,
                            Object[] p_array)
                     throws FunctionException

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

Throws:

FunctionException

See Also:

foldr1(Function2,Collection).

scanr

public static List scanr(Function2 p_function2,
                         Object p_start,
                         Collection 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 List scanr(Function2 p_function2,
                         Object p_start,
                         Object[] 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 List scanr1(Function2 p_function2,
                          Collection 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 List scanr1(Function2 p_function2,
                          Object[] 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 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 boolean all(Function1 p_function1,
                          Collection 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 boolean all(Function1 p_function1,
                          Object[] 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 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 boolean any(Function1 p_function1,
                          Collection 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 boolean any(Function1 p_function1,
                          Object[] p_array)
                   throws FunctionException

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

Throws:

FunctionException

See Also:

any(Function1,Collection).