jedi.functional
Class FunctionalPrimitives

java.lang.Object
  jedi.functional.FunctionalPrimitives

public class FunctionalPrimitives
extends Object

I provide operations of the kind found in Functional Programming languages. This allows you to remove a great deal of clutter from production code. Ideally, you will never need to write another 'for' loop again, and a great deal of explicit conditional logic should be removable as well.

Generally, functions that transform collections (using functors or whatever) preserve the iteration order of the given collection in the result.

Method Summary

static <T> Collection<T>	addAll(Collection<T> list, Iterable<? extends T> iterable) Add all the elements of an iterable to a collection.
static <T> List<T>	append(Collection<? extends T>... collections) Append all of the elements in all of the given collections into one list.
static <T> List<T>	append(Iterable<? extends Iterable<? extends T>> collections) Append all of the elements in all of the given collections into one list.
static <T,R> List<R>	collect(Iterable<T> items, Functor<? super T,R> functor) Apply functor to each element of items and return the list of results.
static <T,R> List<R>	collect(T[] items, Functor<? super T,R> functor) Apply functor to each element of items and return the list of results.
static <T> List<T>	drop(int n, Iterable<T> items) Get all but the first n elements of items.
static <T> List<T>	dropRight(int n, Iterable<T> items) Get all but the last n elements of items.
static <T> T	first(Iterable<? extends T> collection) An alias for head
static <T> Option<T>	firstOption(Iterable<T> items) Get the first item (in iteration order) from a collection as an Option.
static <T,R> List<R>	flatten(Iterable<T> items, Functor<? super T,? extends Iterable<? extends R>> functor) Suppose there is a collection of items (c1, c2, c3), each of which contains a collection i.e. (c1 = (c1_1, c1_2, ...), c2=(c2_1, c2_2, ...).
static <T,R,I extends R> R	fold(I initialValue, Iterable<T> collection, Functor2<R,? super T,R> functor2) Fold passes each item of a collection with an accumulated value to a functor.
static <T,R,I extends R> R	foldPowerset(I initialValue, Collection<T> all, Functor2<R,List<? super T>,R> functor2) Fold over all powersets of the give collection, in no particular order.
static <T> Iterable<T>	forEach(Iterable<T> items, Command<? super T> command) Iterate over a collection of items applying the given command to each
static <K,V> Map<K,List<V>>	group(Iterable<V> toGroup, Functor<? super V,K> keyFunctor) A synonym for partition(Iterable, Functor) Group the elements of a collection such that all elements that are mapped to the same value by a given keyFunctor are in the same group.
static <T> boolean	hasItems(Iterable<T> iterable)
static <T> T	head(Iterable<T> items) Get the first item (in iteration order) from a collection.
static <T> Option<T>	headOption(Iterable<T> items) Get the first item (in iteration order) from a collection as an Option.
static <T> T	headOrDefaultIfEmpty(Iterable<? extends T> items, T defaultValue) Get the first item (in iteration order) from a collection or defaultValue (which may be null) if the collection is empty.
static <T> T	headOrNullIfEmpty(Iterable<T> items) Get the first item (in iteration order) from a collection or null if the collection is empty.
static <T,R,I extends R> R	inject(I initialValue, Iterable<T> collection, Functor2<R,? super T,R> functor2) An alias for fold.
static <T> boolean	isEmpty(Iterable<T> iterable)
static String	join(Iterable<?> items) Join, with default delimiter (empty string)
static String	join(Iterable<?> items, String delimiter)
static String	join(Object[] items, String delimiter) Returns a string created by converting each element of an array to a string, separated by delimiter.
static <T> T	last(Iterable<? extends T> items) Get the last item (in iteration order) from a collection.
static <T> Option<T>	lastOption(Collection<? extends T> items) Get the last item (in iteration order) from a collection as an Option.
static <T> T	lastOrDefaultIfEmpty(Iterable<? extends T> items, T defaultValue) Get the last item (in iteration order) from a collection or defaultValue (which may be null) if the collection is empty.
static <T> T	lastOrNullIfEmpty(Iterable<? extends T> items)
static <R> List<R>	listTabulate(int n, Functor<Integer,R> functor) Returns an n-element list.
static <U,T extends Collection<? extends U>> T	longest(Iterable<T> collections) Find the biggest collection in a collection of collections
static <T> List<T>	makeList(int n, T fill) Returns an n-element list, whose elements are all the value fill.
static <T> T	only(Collection<T> items) Return the one and only item in the given collection.
static <T> List<List<T>>	partition(Iterable<T> items, Filter<T> filter) Partition a collection of items into two sublists using the given filter.
static <K,V> Map<K,List<V>>	partition(Iterable<V> toPartition, Functor<? super V,K> keyFunctor) A synonym for group(Iterable, Functor) Partition the elements of a collection such that all elements that are mapped to the same value by a given keyFunctor are in the same partition.
static <T> T	pop(Iterable<T> items) Removes the last item (in iteration order) from a collection.
static <T> Option<T>	popOption(Iterable<T> items) Removes the last item (in iteration order) from a collection as an Option.
static <T> Set<List<T>>	powerset(Collection<T> all) Return the set of all subsets of the provided collection.
static <T> void	powerset(Collection<T> all, Command<List<? super T>> command) Iterate all powersets of the give collection, in no particular order.
static <T,U,R> List<R>	produce(Iterable<T> left, Iterable<U> right, Functor2<? super T,? super U,R> factory) Create the Cartesian product of two collections, using a functor as a factory of objects to represent the pair-wise products.
static <T> List<T>	reject(Iterable<T> items, Filter<? super T> filter) Filter a collection of items, returning only those that do not match a given filter, this is the inverse of select.
static <T> List<T>	reverse(Iterable<T> items)
static <T> List<T>	select(Iterable<T> items, Filter<? super T> filter) Filter a collection of items, returning only those that match a given filter, this is the inverse of reject.
static <T> Command<T>	sequence(Command<? super T>... commands) Produce a single command that executes each of the given commands in sequence
static <U,T extends Collection<? extends U>> T	shortest(Iterable<T> collections) Find the shortest list in a list of lists
static List	slice(int n, Iterable<List> items) Create a list from the nth elements of the given lists.
static List<String>	split(String item, String regex) Create a list of string by splitting on a regex.
static <T> List<List<T>>	tabulate(Iterable<T> list, int length)
static <T> List<T>	tail(Iterable<T> items) Get all item's (in iteration order) from a collection except the first.
static <T> List<T>	take(int n, Iterable<T> items) Get the first n elements of items.
static <T> List<T>	takeMiddle(int start, int n, Iterable<T> items) Get n middle elements of an Iterable.
static <T> List<T>	takeRight(int n, Iterable<T> items) Get the last n elements of an Iterable.
static List	zip(Iterable<List> lists) Zip interleaves a collection of lists.

Methods inherited from class java.lang.Object

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

Method Detail

append

public static <T> List<T> append(Iterable<? extends Iterable<? extends T>> collections)

Append all of the elements in all of the given collections into one list. All of the elements of the first item in collections are appended first, then the items in the second collection, etc.

See Also:

append(Collection...)

append

public static <T> List<T> append(Collection<? extends T>... collections)

Append all of the elements in all of the given collections into one list. All of the elements of the first item in collections are appended first, then the items in the second collection, etc. Equivalent to append(list(collections))

See Also:

append(Iterable)

collect

public static <T,R> List<R> collect(Iterable<T> items,
                                    Functor<? super T,R> functor)

Apply functor to each element of items and return the list of results.

See Also:

collect(Object[],Functor)

collect

public static <T,R> List<R> collect(T[] items,
                                    Functor<? super T,R> functor)

Apply functor to each element of items and return the list of results. The iteration order of items is preserved in the returned list.

Equivalent to collect(functor, asList(items))

See Also:

collect(Iterable, Functor)

drop

public static <T> List<T> drop(int n,
                               Iterable<T> items)

Get all but the first n elements of items. See SRFI-1

dropRight

public static <T> List<T> dropRight(int n,
                                    Iterable<T> items)

Get all but the last n elements of items. See SRFI-1

flatten

public static <T,R> List<R> flatten(Iterable<T> items,
                                    Functor<? super T,? extends Iterable<? extends R>> functor)

Suppose there is a collection of items (c1, c2, c3), each of which contains a collection i.e. (c1 = (c1_1, c1_2, ...), c2=(c2_1, c2_2, ...). I can produce a collection containing all of the 'leaf' items i.e.(c1_1, c1_2, ..., c2_1, c2_2)

Parameters:

items - The collection of items containing the collection of leaves

functor - Given an element of the 'top' collection, this can obtain the collection of 'leaf' objects to accumulate

addAll

public static <T> Collection<T> addAll(Collection<T> list,
                                       Iterable<? extends T> iterable)

Add all the elements of an iterable to a collection.

fold

public static <T,R,I extends R> R fold(I initialValue,
                                       Iterable<T> collection,
                                       Functor2<R,? super T,R> functor2)

Fold passes each item of a collection with an accumulated value to a functor.

For example, to sum the elements of a list:

           Functor2<Integer, Integer> summer = new Functor2<Integer, Integer>() {
                public Integer execute(Integer accumulator, Integer value) {
                        return accumulator + value;
                }
           };
           fold(10, summer, list(1, 2, 3, 4)) will return 20 (initial value of 10 + the sum of 1 .. 4)
 

For a more comprehensive description, see SRFI-1

forEach

public static <T> Iterable<T> forEach(Iterable<T> items,
                                      Command<? super T> command)

Iterate over a collection of items applying the given command to each

group

public static <K,V> Map<K,List<V>> group(Iterable<V> toGroup,
                                         Functor<? super V,K> keyFunctor)

A synonym for partition(Iterable, Functor) Group the elements of a collection such that all elements that are mapped to the same value by a given keyFunctor are in the same group. The groups are returned as a map in which each value is a collection of values in one group and whose key is the value returned by the keyFunctor for all items in the group.

partition

public static <K,V> Map<K,List<V>> partition(Iterable<V> toPartition,
                                             Functor<? super V,K> keyFunctor)

A synonym for group(Iterable, Functor) Partition the elements of a collection such that all elements that are mapped to the same value by a given keyFunctor are in the same partition. The groups are returned as a map in which each value is a collection of values in one partition and whose key is the value returned by the keyFunctor for all items in the group.

head

public static <T> T head(Iterable<T> items)

Get the first item (in iteration order) from a collection. The collection must contain at least one item or an AssertionError will be thrown.

Returns:

the first item in the collection

Throws:

AssertionError - if the collection is empty

See Also:

only(Collection), headOrNullIfEmpty(Iterable), headOrDefaultIfEmpty(Iterable, Object)

headOrDefaultIfEmpty

public static <T> T headOrDefaultIfEmpty(Iterable<? extends T> items,
                                         T defaultValue)

Get the first item (in iteration order) from a collection or defaultValue (which may be null) if the collection is empty.

Returns:

the first item in the collection or defaultValue if the collection is empty

See Also:

only(Collection), head(Iterable), headOrNullIfEmpty(Iterable)

headOrNullIfEmpty

public static <T> T headOrNullIfEmpty(Iterable<T> items)

Get the first item (in iteration order) from a collection or null if the collection is empty.

Returns:

the first item in the collection or null if the collection is empty

See Also:

only(Collection), head(Iterable), headOrDefaultIfEmpty(Iterable, Object)

headOption

public static <T> Option<T> headOption(Iterable<T> items)

Get the first item (in iteration order) from a collection as an Option.

Parameters:

items -

Returns:

the first item (in iteration order) from a collection as Some or None if the collection is empty.

last

public static <T> T last(Iterable<? extends T> items)

Get the last item (in iteration order) from a collection. The collection must contain at least one item or an AssertionError will be thrown.

Returns:

the last item in the collection

Throws:

AssertionError - if the collection is empty

See Also:

only(Collection), lastOrNullIfEmpty(Iterable), lastOrDefaultIfEmpty(Iterable, Object)

lastOrDefaultIfEmpty

public static <T> T lastOrDefaultIfEmpty(Iterable<? extends T> items,
                                         T defaultValue)

Get the last item (in iteration order) from a collection or defaultValue (which may be null) if the collection is empty.

Returns:

the last item in the collection or defaultValue if the collection is empty

See Also:

only(Collection), last(Iterable), lastOrNullIfEmpty(Iterable)

lastOrNullIfEmpty

public static <T> T lastOrNullIfEmpty(Iterable<? extends T> items)

lastOption

public static <T> Option<T> lastOption(Collection<? extends T> items)

Get the last item (in iteration order) from a collection as an Option.

Returns:

the last item as a Some or None if the collection is empty.

first

public static <T> T first(Iterable<? extends T> collection)

An alias for head

See Also:

head(Iterable)

firstOption

public static <T> Option<T> firstOption(Iterable<T> items)

Get the first item (in iteration order) from a collection as an Option.

Parameters:

items -

Returns:

the first item (in iteration order) from a collection as Some or None if the collection is empty.

inject

public static <T,R,I extends R> R inject(I initialValue,
                                         Iterable<T> collection,
                                         Functor2<R,? super T,R> functor2)

An alias for fold.

See Also:

fold(Object, Iterable, Functor2)

join

public static String join(Iterable<?> items)

Join, with default delimiter (empty string)

See Also:

join(Object[], String)

join

public static String join(Iterable<?> items,
                          String delimiter)

join

public static String join(Object[] items,
                          String delimiter)

Returns a string created by converting each element of an array to a string, separated by delimiter. Emulates Array.join in Ruby.

listTabulate

public static <R> List<R> listTabulate(int n,
                                       Functor<Integer,R> functor)

Returns an n-element list. Element i of the list, where 0 <= i < n, is produced by the functor. For a more comprehensive description, see SRFI-1

Parameters:

n - the length of the list

functor - the functor taking an integer and returning an

longest

public static <U,T extends Collection<? extends U>> T longest(Iterable<T> collections)

Find the biggest collection in a collection of collections

Parameters:

collections -

Returns:

the shortest list

makeList

public static <T> List<T> makeList(int n,
                                   T fill)

Returns an n-element list, whose elements are all the value fill. For a more comprehensive description, see SRFI-1

only

public static <T> T only(Collection<T> items)

Return the one and only item in the given collection.

Returns:

the item in the collection

Throws:

AssertionError - if the collection contains less or more than one item

See Also:

head(Iterable), headOrNullIfEmpty(Iterable)

produce

public static <T,U,R> List<R> produce(Iterable<T> left,
                                      Iterable<U> right,
                                      Functor2<? super T,? super U,R> factory)

Create the Cartesian product of two collections, using a functor as a factory of objects to represent the pair-wise products.

reject

public static <T> List<T> reject(Iterable<T> items,
                                 Filter<? super T> filter)

Filter a collection of items, returning only those that do not match a given filter, this is the inverse of select.

See Also:

select(Iterable, Filter)

reverse

public static <T> List<T> reverse(Iterable<T> items)

select

public static <T> List<T> select(Iterable<T> items,
                                 Filter<? super T> filter)

Filter a collection of items, returning only those that match a given filter, this is the inverse of reject.

See Also:

reject(Iterable, Filter)

sequence

public static <T> Command<T> sequence(Command<? super T>... commands)

Produce a single command that executes each of the given commands in sequence

shortest

public static <U,T extends Collection<? extends U>> T shortest(Iterable<T> collections)

Find the shortest list in a list of lists

Parameters:

collections -

Returns:

the shortest list

hasItems

public static <T> boolean hasItems(Iterable<T> iterable)

isEmpty

public static <T> boolean isEmpty(Iterable<T> iterable)

slice

public static List slice(int n,
                         Iterable<List> items)

Create a list from the nth elements of the given lists.

split

public static List<String> split(String item,
                                 String regex)

Create a list of string by splitting on a regex.

See Also:

String.split(java.lang.String, int)

tail

public static <T> List<T> tail(Iterable<T> items)

Get all item's (in iteration order) from a collection except the first. The collection must contain at least one item or an AssertionError will be thrown.

Returns:

all items except the first

Throws:

AssertionError - if the collection contains less or more than one item

See Also:

only(Collection), headOrNullIfEmpty(Iterable), headOrDefaultIfEmpty(Iterable, Object)

take

public static <T> List<T> take(int n,
                               Iterable<T> items)

Get the first n elements of items.

See Also:

SRFI-1

takeRight

public static <T> List<T> takeRight(int n,
                                    Iterable<T> items)

Get the last n elements of an Iterable.

See Also:

SRFI-1

takeMiddle

public static <T> List<T> takeMiddle(int start,
                                     int n,
                                     Iterable<T> items)

Get n middle elements of an Iterable.

zip

public static List zip(Iterable<List> lists)

Zip interleaves a collection of lists. If zip is passed n lists, it returns a list as long as the shortest of these lists, each element of which is an n-element list comprised of the corresponding elements from the parameter lists.

See SRFI-1

Parameters:

lists -

Returns:

zipped lists

tabulate

public static <T> List<List<T>> tabulate(Iterable<T> list,
                                         int length)

Returns:

a list of lists by splitting the given list into lists of length length.

pop

public static <T> T pop(Iterable<T> items)

Removes the last item (in iteration order) from a collection. The collection must contain at least one item or an AssertionError will be thrown. Emulates Array.pop in Ruby.

Returns:

the last item in the collection

Throws:

AssertionError - if the collection contains less or more than one item

See Also:

only(Collection), headOrNullIfEmpty(Iterable), headOrDefaultIfEmpty(Iterable, Object)

popOption

public static <T> Option<T> popOption(Iterable<T> items)

Removes the last item (in iteration order) from a collection as an Option.

Returns:

the last item in the collection as Some or None if the list is empty.

partition

public static <T> List<List<T>> partition(Iterable<T> items,
                                          Filter<T> filter)

Partition a collection of items into two sublists using the given filter.

Parameters:

items -

Returns:

a list whose first element as a list of items in list that pass the filter, the second item is a list of elements that did not pass the filter.

powerset

public static <T> Set<List<T>> powerset(Collection<T> all)

Return the set of all subsets of the provided collection.

For example, if all is the list ("x","y","z"), the return will be set containing 8 lists as follows:

• () - empty set
• ("x")
• ("y")
• ("z")
• ("x","y")
• ("x","z")
• ("y","z")
• ("x","y","z")

See http://en.wikipedia.org/wiki/Power_set

See Also:

powerset(Collection, Command), foldPowerset(Object, Collection, Functor2)

powerset

public static <T> void powerset(Collection<T> all,
                                Command<List<? super T>> command)

Iterate all powersets of the give collection, in no particular order.

See Also:

powerset(Collection), foldPowerset(Object, Collection, Functor2)

foldPowerset

public static <T,R,I extends R> R foldPowerset(I initialValue,
                                               Collection<T> all,
                                               Functor2<R,List<? super T>,R> functor2)

Fold over all powersets of the give collection, in no particular order.

See Also:

powerset(Collection), powerset(Collection, Command), fold(Object, Iterable, Functor2)