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 functional programming patterns.

Note about Folding

Folding consists of using a function that requires two more parameters, or an object and one more parameter (in the latter case, this must be an InstanceFunction), and applying it to a list of elements, each time using the result of the previous function call as the first parameter to the next function call.

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

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

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

Folding a list from the right using a function f, a starting parameter p, and a list 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(Function p_function, List p_list) Determines if all of the elements of the list satisfy the condition represented by the given function.
static boolean	all(Function p_function, Object[] p_array) Determines if all of the elements of the array satisfy the condition represented by the given function, by converting the array to a list and calling all(Function,List).
static boolean	and(boolean[] p_array) Returns the result of &&ing the boolean values in the given array.
static boolean	and(Boolean[] p_array) Returns the result of &&ing the Boolean values in the given array.
static boolean	and(List p_list) Returns the result of &&ing the Boolean values in the given list.
static boolean	any(Function p_function, List p_list) Determines whether any of the elements of the list satisfy the condition represented by the given function.
static boolean	any(Function p_function, Object[] p_array) Determines whether any of the elements of the array satisfy the condition represented by the given function, by converting the array to a list and calling any(Function,List).
static String	concat(List p_list) Concatenates the string representations of a list of objects to return a single string.
static String	concat(Object[] p_objects) Concatenates an array of strings by first converting the array to a list, then calling concat(List).
static List	filter(Function p_function, List p_list) Filters a list to return only those elements for which the given function returns true.
static List	filter(Function p_function, Object[] p_array) Filters an array to return only those elements for which the given function returns true.
static List	filterNot(Function p_function, List p_list) Filters a list to return only those elements for which the given function returns false.
static List	filterNot(Function p_function, Object[] p_array) Filters a list to return only those elements for which the given function returns false.
static Object	foldl(Function p_function, Object p_start, List p_list) Folds a list from the left using the given function and starting parameter.
static Object	foldl(Function p_function, Object p_start, Object[] p_array) Folds an array from the left using the given function and starting parameter, first converting the array to a list and then calling foldl(Function,Object,List).
static Object	foldl1(Function p_function, List p_list) Folds a list from the left using the given function.
static Object	foldl1(Function p_function, Object[] p_array) Folds an array from the left using the given function, first converting the array to a list and then calling foldl1(Function,List).
static Object	foldr(Function p_function, Object p_start, List p_list) Folds a list from the right using the given function and starting parameter.
static Object	foldr(Function p_function, Object p_start, Object[] p_array) Folds an array from the right using the given function and starting parameter, first converting the array to a list and then calling foldr(Function,Object,List).
static Object	foldr1(Function p_function, List p_list) Folds a list from the right using the given function.
static Object	foldr1(Function p_function, Object[] p_array) Folds an array from the right using the given function, first converting the array to a list and then calling foldr1(Function,List).
static List	intersperse(Object p_object, List p_list) Intersperses the specified object into the given list, such that the object is inserted between each pair of elements of the list.
static List	intersperse(Object p_object, Object[] p_array) Intersperses the specified object into the given array, such that the object is inserted between each pair of elements of the array.
static List	map(Function p_function, List p_list) Maps a function to a list of parameters, by applying in turn each element of the list as a parameter to the function and calling it, and returns a list of the results.
static List	map(Function p_function, Object[] p_array) Maps a function to an array of parameters, first converting the array to a List and then calling map(Function,List).
static boolean	or(boolean[] p_array) Returns the result of ||ing the boolean values in the given array.
static boolean	or(Boolean[] p_array) Returns the result of ||ing the Boolean values in the given array.
static boolean	or(List p_list) Returns the result of ||ing the Boolean values in the given list.
static List	scanl(Function p_function, Object p_start, List p_list) Scans a list to return successive reduced values from the left.
static List	scanl(Function p_function, Object p_start, Object[] p_array) Scans a list to return successive reduced values from the left, first converting the array to a list and then calling scanl(Function,Object,List).
static List	scanl1(Function p_function, List p_list) Scans a list to return successive reduced values from the left, using the first element of the list as a starting parameter.
static List	scanl1(Function p_function, Object[] p_array) Scans a list to return successive reduced values from the left, first converting the array to a list and then calling scanl1(Function,List).
static List	scanr(Function p_function, Object p_start, List p_list) Scans a list to return successive reduced values from the right.
static List	scanr(Function p_function, Object p_start, Object[] p_array) Scans a list to return successive reduced values from the right, first converting the array to a list and then calling scanr(Function,Object,List).
static List	scanr1(Function p_function, List p_list) Scans a list to return successive reduced values from the right, using the first element of the list as a starting parameter.
static List	scanr1(Function p_function, Object[] p_array) Scans a list to return successive reduced values from the right, first converting the array to a list and then calling scanr1(Function,List).
static int	sum(List p_list) Given a List of Numbers, returns the sum of their int values.

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(Function p_function,
                       List p_list)
                throws FunctionException

Maps a function to a list of parameters, by applying in turn each element of the list as a parameter to the function and calling it, and returns a list of the results.

Parameters:

p_function - the function to be mapped.

p_list - the list of objects or parameters on which to map the function.

Returns:

a list of the results of calling the function on each object or parameter of the list. If the list 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(Function p_function,
                       Object[] p_array)

Maps a function to an array of parameters, first converting the array to a List and then calling map(Function,List).

See Also:

map(Function,List).

filter

public static List filter(Function p_function,
                          List p_list)
                   throws FunctionException

Filters a list to return only those elements for which the given function returns true. Thus the function must accept one more parameter, or have all parameters but no object (in the case of an InstanceFunction, and return a result of type boolean or Boolean.

Parameters:

p_function - the function to use to filter the list.

p_list - the list to be filtered.

Returns:

a list of elements for which the condition represented by the function returns true. If the specified list is null or empty, an empty list is returned.

Throws:

FunctionException - thrown if the function is null, if it does not return a result of type boolean or Boolean, or if an exception occurs while using the function.

filter

public static List filter(Function p_function,
                          Object[] p_array)

Filters an array to return only those elements for which the given function returns true. After converting the array to a List, the filter(Function,List) method is called.

See Also:

filter(Function,List)

filterNot

public static List filterNot(Function p_function,
                             List p_list)
                      throws FunctionException

Filters a list to return only those elements for which the given function returns false. This is equivalent to calling filter(Function,List) with a ComposedFunction of Operators.not and the given function.

Throws:

FunctionException

See Also:

filter(Function,List)., Operators.not

filterNot

public static List filterNot(Function p_function,
                             Object[] p_array)

Filters a list to return only those elements for which the given function returns false. After converting the array to a List, the filterNot(Function,List) method is called.

See Also:

filterNot(Function,List)

foldl

public static Object foldl(Function p_function,
                           Object p_start,
                           List p_list)
                    throws FunctionException

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

Parameters:

p_function - the function to use while folding.

p_start - the starting parameter to the function.

p_list - the list of elements to be folded.

Returns:

the result of folding the elements of the list 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(Function p_function,
                           Object p_start,
                           Object[] p_array)

Folds an array from the left using the given function and starting parameter, first converting the array to a list and then calling foldl(Function,Object,List).

See Also:

foldl(Function,Object,List).

foldl1

public static Object foldl1(Function p_function,
                            List p_list)
                     throws FunctionException

Folds a list from the left 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_function - the function to use while folding.

p_list - the list of elements to be folded.

Returns:

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

Throws:

FunctionException - thrown if the list is null or empty.

See Also:

foldl(Function,Object,List)

foldl1

public static Object foldl1(Function p_function,
                            Object[] p_array)
                     throws FunctionException

Folds an array from the left using the given function, first converting the array to a list and then calling foldl1(Function,List).

Throws:

FunctionException

See Also:

foldl1(Function,List).

foldr

public static Object foldr(Function p_function,
                           Object p_start,
                           List p_list)

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

Parameters:

p_function - the function to use while folding.

p_start - the starting parameter to the function.

p_list - the list of elements to be folded.

Returns:

the result of folding the elements of the list 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(Function p_function,
                           Object p_start,
                           Object[] p_array)

Folds an array from the right using the given function and starting parameter, first converting the array to a list and then calling foldr(Function,Object,List).

See Also:

foldr(Function,Object,List).

foldr1

public static Object foldr1(Function p_function,
                            List p_list)
                     throws FunctionException

Folds a list 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_function - the function to use while folding.

p_list - the list of elements to be folded.

Returns:

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

Throws:

FunctionException - thrown if the list is null or empty.

See Also:

foldr(Function,Object,List)

foldr1

public static Object foldr1(Function p_function,
                            Object[] p_array)
                     throws FunctionException

Folds an array from the right using the given function, first converting the array to a list and then calling foldr1(Function,List).

Throws:

FunctionException

See Also:

foldr1(Function,List).

scanl

public static List scanl(Function p_function,
                         Object p_start,
                         List p_list)
                  throws FunctionException

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

Parameters:

p_function - the function used for scanning.

p_start - the starting parameter to the function.

p_list - the list of elements to be scanned.

Returns:

successive reduced values from the left.

Throws:

FunctionException - thrown if the function is null.

scanl

public static List scanl(Function p_function,
                         Object p_start,
                         Object[] p_array)
                  throws FunctionException

Scans a list to return successive reduced values from the left, first converting the array to a list and then calling scanl(Function,Object,List).

Throws:

FunctionException

See Also:

scanl(Function,Object,List).

scanl1

public static List scanl1(Function p_function,
                          List p_list)
                   throws FunctionException

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

Throws:

FunctionException

See Also:

scanl(Function,Object,List).

scanl1

public static List scanl1(Function p_function,
                          Object[] p_array)
                   throws FunctionException

Scans a list to return successive reduced values from the left, first converting the array to a list and then calling scanl1(Function,List).

Throws:

FunctionException

See Also:

scanl1(Function,List).

scanr

public static List scanr(Function p_function,
                         Object p_start,
                         List p_list)
                  throws FunctionException

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

Parameters:

p_function - the function used for scanning.

p_start - the starting parameter to the function.

p_list - the list 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(Function p_function,
                         Object p_start,
                         Object[] p_array)
                  throws FunctionException

Scans a list to return successive reduced values from the right, first converting the array to a list and then calling scanr(Function,Object,List).

Throws:

FunctionException

See Also:

scanr(Function,Object,List).

scanr1

public static List scanr1(Function p_function,
                          List p_list)
                   throws FunctionException

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

Throws:

FunctionException

See Also:

scanr(Function,Object,List).

scanr1

public static List scanr1(Function p_function,
                          Object[] p_array)
                   throws FunctionException

Scans a list to return successive reduced values from the right, first converting the array to a list and then calling scanr1(Function,List).

Throws:

FunctionException

See Also:

scanr1(Function,List).

and

public static boolean and(List p_list)
                   throws FunctionException

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

Parameters:

p_list - the list of Boolean values to be &&ed.

Returns:

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

Throws:

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

and

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

Returns the result of &&ing the Boolean values in the given array. The array is converted to a list and and(List) is called.

Throws:

FunctionException

See Also:

and(List).

and

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

Returns the result of &&ing the boolean values in the given array. The array is converted to a list and and(List) is called.

Throws:

FunctionException

See Also:

and(List).

all

public static boolean all(Function p_function,
                          List p_list)

Determines if all of the elements of the list satisfy the condition represented by the given function. Thus the function must accept one more parameter, or be an InstanceFunction for which the object has not been specified, and return a boolean or Boolean result.

Parameters:

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

p_list - the list of elements to be tested against the condition.

Returns:

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

all

public static boolean all(Function p_function,
                          Object[] p_array)

Determines if all of the elements of the array satisfy the condition represented by the given function, by converting the array to a list and calling all(Function,List).

See Also:

all(Function,List).

or

public static boolean or(List p_list)
                  throws FunctionException

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

Parameters:

p_list - the list of Boolean values to be ||ed.

Returns:

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

Throws:

FunctionException

or

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

Returns the result of ||ing the Boolean values in the given array. The array is converted to a list and or(List) is called.

Throws:

FunctionException

See Also:

or(List).

or

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

Returns the result of ||ing the boolean values in the given array. The array is converted to a list and or(List) is called.

Throws:

FunctionException

See Also:

or(List).

any

public static boolean any(Function p_function,
                          List p_list)

Determines whether any of the elements of the list satisfy the condition represented by the given function. Thus the function must accept one more parameter, or be an InstanceFunction for which the object has not been specified, and return a boolean or Boolean result.

Parameters:

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

p_list - the list of elements to be tested against the condition.

Returns:

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

any

public static boolean any(Function p_function,
                          Object[] p_array)

Determines whether any of the elements of the array satisfy the condition represented by the given function, by converting the array to a list and calling any(Function,List).

See Also:

any(Function,List).

intersperse

public static List intersperse(Object p_object,
                               List p_list)

Intersperses the specified object into the given list, such that the object is inserted between each pair of elements of the list. For example, calling intersperse(", ", ["a","b","c","d"]) returns ["a",", ","b",", ""c",", ""d"]. Using concat(List) on this last result will return "a, b, c, d".

Parameters:

p_object - the object to be interspersed into the list.

p_list - the list to be interspersed.

Returns:

a new list consisting of the original list with the specified object interspersed.

intersperse

public static List intersperse(Object p_object,
                               Object[] p_array)

Intersperses the specified object into the given array, such that the object is inserted between each pair of elements of the array. The array is first converted to a List, and then intersperse(Object,List) is called.

See Also:

intersperse(Object,List).

concat

public static String concat(List p_list)

Concatenates the string representations of a list of objects to return a single string.

Parameters:

p_list - the list of objects to be concatenated.

Returns:

the single string that results from concatenating the list of objects.

concat

public static String concat(Object[] p_objects)

Concatenates an array of strings by first converting the array to a list, then calling concat(List).

See Also:

concat(List).

sum

public static int sum(List p_list)

Given a List of Numbers, returns the sum of their int values.

Parameters:

p_list - the list of Numbers to add up.

Returns:

the sum of the int values of the list.