util
Class Functional

java.lang.Object
  util.Functional

public final class Functional
extends Object

A few utility methods for functional-ish programming, including concise string manipulation and composition. Along with Builders, should be useful in cutting down on lengthy code duplication in library classes.

Nested Class Summary

static class	Functional.Iteration<T> An adaptor for iterating in a foreach loop, given an iterator.
static class	Functional.Range An iterable representing a range of integers.
static class	Functional.Zipper<A,B> An iterable over two iterables, pairing them element by element.

Method Summary

static <T> Iterable<T>	backward(Iterable<T> coll) Iterate over a given iterable backwards.
static <T> Iterable<T>	backward(Iterator<T> iter) Iterate over a given iterator backwards.
static <T> Iterable<T>	backward(List<T> list) Iterate over a given list backwards.
static <T> Iterable<Pair<Integer,T>>	enumerate(Iterable<T> coll) Iterate over (index, element) pairs corresponding to each element of an iterable with its index.
static <T> Iterable<Pair<Integer,T>>	enumerate(T[] arr) Iterate over (index, element) pairs corresponding to each element of an array with its index.
static <T> String	join(Collection<T> coll, String sep) Concatenate the string represetations of several objects, with a separator.
static <T> String	join(T[] arr, String sep) Join an array into a string, separating the elements with the given separator string.
static <T> String	quoteAndJoin(Collection<T> coll, String sep) Put typographer's (Unicode) quotes around a collection of objects, delimited by some separator.
static <T> String	quoteAndJoin(T[] coll, String sep) Put typographer's (Unicode) quotes around an array of objects, delimited by some separator.
static Functional.Range	range(int stop) Construct the integer range [0, stop), as an efficient iterable.
static Functional.Range	range(int start, int stop) Construct the integer range [start, stop), as an efficient iterable.
static Functional.Range	range(int start, int stop, int step) Construct the integer range from start (inclusive) to stop (exclusive), in increments of step, as an efficient iterable.
static <T,C extends Collection<T>> Pair<T[],T[]>	separate(C coll, Predicate<T> pred) Divide a collection into those elements satisfying and those not satisfying a given predicate, returning two arrays.
static <T,C extends Collection<T>,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2>	separate(C coll, Predicate<T> pred, C1 tgtTrue, C2 tgtFalse) Divide a collection into those elements satisfying and those not satisfying a given predicate.
static <T> Pair<T[],T[]>	separate(T[] arr, Predicate<T> pred) Divide an array into those elements satisfying and those not satisfying a given predicate, returning two arrays.
static <T,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2>	separate(T[] arr, Predicate<T> pred, C1 tgtTrue, C2 tgtFalse) Divide an array into those elements satisfying and those not satisfying a given predicate.
static <T,C extends Collection<T>> Pair<T[],T[]>	span(C coll, Predicate<T> pred) Split a collection at the first element not satisfying a predicate, returning two arrays.
static <T,C extends Collection<T>,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2>	span(C coll, Predicate<T> pred, C1 tgt1, C2 tgt2) Split a collection at the first element not satisfying a predicate.
static <T> Pair<T[],T[]>	span(T[] arr, Predicate<T> pred) Split an array at the first element not satisfying a predicate, returning two arrays.
static <T,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2>	span(T[] arr, Predicate<T> pred, C1 tgt1, C2 tgt2) Split an array at the first element not satisfying a predicate.
static <T> String[]	wrapEach(Collection<T> coll, String prefix, String suffix) Add a prefix and/or suffix to the string representation of each element in a collection.
static <T> String[]	wrapEach(Iterable<T> coll, String prefix, String suffix) Add a prefix and/or suffix to the string representation of each element in any iterable.
static <T> String[]	wrapEach(T[] arr, String prefix, String suffix) Add a prefix and/or suffix to the string representation of each element in an array.
static <A,B> Functional.Zipper<A,B>	zip(A[] arrA, B[] arrB) Iterate over two arrays at once.
static <A,B> Functional.Zipper<A,B>	zip(Iterable<A> collA, Iterable<B> collB) Iterate over two iterables at once, pairing them element by element.
static <A,B> Functional.Zipper<A,B>	zip(Iterator<A> iterA, Iterator<B> iterB) Iterate over two iterators at once.

Methods inherited from class java.lang.Object

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

Method Detail

join

public static <T> String join(Collection<T> coll,
                              String sep)

Concatenate the string represetations of several objects, with a separator.

See the example under join(Object[], String).

Type Parameters:

T - The type of the objects to concatenate.

Parameters:

coll - The objects to concatenate.

sep - The separator string.

Returns:

A string with the objects separated by the separator.

join

public static <T> String join(T[] arr,
                              String sep)

Join an array into a string, separating the elements with the given separator string.

      String[] things = { "eggs", "bacon", "spam" };
      System.out.println(Functional.join(things, ", ");
      System.out.println(Functional.join(things, " ... ");
  

Expected output:

      eggs, bacon, spam
      eggs ... bacon ... spam
  

Type Parameters:

T - The element type of the array.

Parameters:

arr - The array with the elements to concatenate.

sep - The string to separate the elements.

Returns:

The string concatenation of the elements of the array.

wrapEach

public static <T> String[] wrapEach(Collection<T> coll,
                                    String prefix,
                                    String suffix)

Add a prefix and/or suffix to the string representation of each element in a collection.

See the example under wrapEach(Object[], String, String).

Type Parameters:

T - The element type of the collection.

Parameters:

coll - The collection.

prefix - The string to put before each element.

suffix - The string to put after each element.

Returns:

For each element, the prefix plus the element's string representation plus the suffix.

wrapEach

public static <T> String[] wrapEach(Iterable<T> coll,
                                    String prefix,
                                    String suffix)

Add a prefix and/or suffix to the string representation of each element in any iterable.

See the example under wrapEach(Object[], String, String).

Type Parameters:

T - The element type of the iterable.

Parameters:

coll - The iterable.

prefix - The string to put before each element.

suffix - The string to put after each element.

Returns:

For each element, the prefix plus the element's string representation plus the suffix.

wrapEach

public static <T> String[] wrapEach(T[] arr,
                                    String prefix,
                                    String suffix)

Add a prefix and/or suffix to the string representation of each element in an array.

For example, say we want to generate Java code to count from 1 to 10.

      int[] numbers = { 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 };
      String[] lines = Functional.wrapEach(numbers,
          "System.out.println(", ");");
      for (String line : lines)
          System.out.println(line);
  

Expected output (abbreviated):

      System.out.println(1);
      System.out.println(2);
      ...
      System.out.println(10);
  

Type Parameters:

T - The element type of the array.

Parameters:

arr - The array.

prefix - The string to put before each element.

suffix - The string to put after each element.

Returns:

For each element, the prefix plus the element's string representation plus the suffix.

quoteAndJoin

public static <T> String quoteAndJoin(Collection<T> coll,
                                      String sep)

Put typographer's (Unicode) quotes around a collection of objects, delimited by some separator.

Type Parameters:

T - The element type of the collection.

Parameters:

coll - The collection.

sep - The string to separate the elements.

Returns:

The joined, quoted, formatted string.

quoteAndJoin

public static <T> String quoteAndJoin(T[] coll,
                                      String sep)

Put typographer's (Unicode) quotes around an array of objects, delimited by some separator.

Type Parameters:

T - The element type of the array.

Parameters:

coll - The array.

sep - The string to separate the elements.

Returns:

The joined, quoted, formatted string.

backward

public static <T> Iterable<T> backward(Iterator<T> iter)

Iterate over a given iterator backwards.

Note that this is likely to be inefficient, as a list of the values given by the iterator must be built at construction and then kept for the duration of the iteration.

Type Parameters:

T - The element type of the iterator.

Parameters:

iter - The iterator to reverse.

Returns:

An iterable which gives the same elements as iter, only backwards.

backward

public static <T> Iterable<T> backward(List<T> list)

Iterate over a given list backwards.

If the list is of a type that implements RandomAccess, this is efficient, since one need only go through the indices backwards. Otherwise, a temporary ArrayList is required.

Type Parameters:

T - The element type of the iterator.

Parameters:

list - The list over which to iterate.

Returns:

An iterable which gives the elements of list in reverse.

backward

public static <T> Iterable<T> backward(Iterable<T> coll)

Iterate over a given iterable backwards. Inefficient for large iterables.

Type Parameters:

T - The element type of the iterable.

Parameters:

coll - The iterable to reverse.

Returns:

An iterable which gives the elements that coll would give, only in reverse.

range

public static Functional.Range range(int start,
                                     int stop,
                                     int step)

Construct the integer range from start (inclusive) to stop (exclusive), in increments of step, as an efficient iterable.

Parameters:

start - The first integer in the range.

stop - The first integer outside of the range.

step - The increment between each element.

Returns:

An Iterable<Integer> over the range.

range

public static Functional.Range range(int start,
                                     int stop)

Construct the integer range [start, stop), as an efficient iterable.

Parameters:

start - The first integer in the range.

stop - The first integer outside the range.

Returns:

An Iterable<Integer> over [start, stop).

range

public static Functional.Range range(int stop)

Construct the integer range [0, stop), as an efficient iterable.

Parameters:

stop - The first integer outside the range.

Returns:

An Iterable<Integer> over [0, stop).

zip

public static <A,B> Functional.Zipper<A,B> zip(Iterable<A> collA,
                                               Iterable<B> collB)

Iterate over two iterables at once, pairing them element by element.

Type Parameters:

A - The type of the first elements.

B - The type of the second elements.

Parameters:

collA - The first iterable over which to iterate.

collB - The second iterable.

Returns:

An iterable giving the elements from both, in pairs.

zip

public static <A,B> Functional.Zipper<A,B> zip(Iterator<A> iterA,
                                               Iterator<B> iterB)

Iterate over two iterators at once.

Type Parameters:

A - The element type of the first iterator.

B - The element type of the second iterator.

Parameters:

iterA - The first iterator.

iterB - The second iterator.

Returns:

An iterable giving the elements yielded by both iterators.

zip

public static <A,B> Functional.Zipper<A,B> zip(A[] arrA,
                                               B[] arrB)

Iterate over two arrays at once.

Type Parameters:

A - The element type of the first array.

B - The element type of the second array.

Parameters:

arrA - The first array.

arrB - The second array.

Returns:

An iterable giving the elements from both, in pairs.

enumerate

public static <T> Iterable<Pair<Integer,T>> enumerate(Iterable<T> coll)

Iterate over (index, element) pairs corresponding to each element of an iterable with its index.

Type Parameters:

T - The element type.

Parameters:

coll - The collection to enumerate.

Returns:

(index, element) for element == coll.get(index).

enumerate

public static <T> Iterable<Pair<Integer,T>> enumerate(T[] arr)

Iterate over (index, element) pairs corresponding to each element of an array with its index.

Type Parameters:

T - The element type.

Parameters:

arr - The array to enumerate.

Returns:

(index, element) for element == arr[index].

separate

public static <T> Pair<T[],T[]> separate(T[] arr,
                                         Predicate<T> pred)

Divide an array into those elements satisfying and those not satisfying a given predicate, returning two arrays.

For example, given the predicate isEven in the example from Predicate:

      Integer[] numbers = { 1, 2, 3, 4, 5 };
      Pair<Integer> evens_odds = Functional.separate(numbers, isEven);
      Integer[] evens = evens_odds.a, odds = evens_odds.b;
      System.out.format("Evens: %s\nOdds: %s\n", 
          Functional.join(evens, ", "), Functional.join(odds, ", "));
  

(see join(Object[], String))

The output should be:

      Evens: 2, 4
      Odds: 1, 3, 5
  

Type Parameters:

T - The element type of the array.

Parameters:

arr - The array to divide.

pred - The predicate to apply.

Returns:

A pair of arrays, containing respectively those elements satisfying and not satisfying the predicate.

separate

public static <T,C extends Collection<T>> Pair<T[],T[]> separate(C coll,
                                                                 Predicate<T> pred)

Divide a collection into those elements satisfying and those not satisfying a given predicate, returning two arrays.

See the example under separate(Object[], Predicate).

Type Parameters:

T - The element type of the collection.

C - The collection type.

Parameters:

coll - The collection to divide.

pred - The predicate to apply.

Returns:

A pair of arrays, containing respectively those elements satisfying and not satisfying the predicate.

separate

public static <T,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2> separate(T[] arr,
                                                                                         Predicate<T> pred,
                                                                                         C1 tgtTrue,
                                                                                         C2 tgtFalse)

Divide an array into those elements satisfying and those not satisfying a given predicate.

For example, given the predicate isEven in the example from Predicate:

      Integer[] numbers = { 1, 2, 3, 4, 5 };
      List<Integer> evens, odds;
      evens = new ArrayList<Integer>();
      odds = new ArrayList<Integer>();
      Functional.separate(numbers, isEven, evens, odds);
      System.out.format("Evens: %s\nOdds: %s\n", evens, odds);
  

The output should be:

      Evens: [2, 4]
      Odds: [1, 3, 5]
  

Type Parameters:

T - The element type of the array.

C1 - The type of the first target collection.

C2 - The type of the second target collection.

Parameters:

arr - The array to divide.

pred - The predicate to apply.

tgtTrue - The collection receiving those elements satisfying the predicate.

tgtFalse - The collection receiving those elements not satisfying the predicate.

Returns:

Pair.of(tgtTrue, tgtFalse), as a convenience.

separate

public static <T,C extends Collection<T>,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2> separate(C coll,
                                                                                                                 Predicate<T> pred,
                                                                                                                 C1 tgtTrue,
                                                                                                                 C2 tgtFalse)

Divide a collection into those elements satisfying and those not satisfying a given predicate.

See the example under separate(Object[], Predicate, Collection, Collection).

Type Parameters:

T - The element type of the collection.

C - The collection type.

C1 - The type of the first target collection.

C2 - The type of the second target collection.

Parameters:

coll - The collection to divide.

pred - The predicate to apply.

tgtTrue - The collection receiving those elements satisfying the predicate.

tgtFalse - The collection receiving those elements not satisfying the predicate.

Returns:

Pair.of(tgtTrue, tgtFalse), as a convenience.

span

public static <T> Pair<T[],T[]> span(T[] arr,
                                     Predicate<T> pred)

Split an array at the first element not satisfying a predicate, returning two arrays.

For example, given the predicate isEven in the example from Predicate:

      Integer[] numbers = { 2, 4, 6, 7, 8, 9, 10 };
      Pair<Integer[], Integer[]> evenSpan_rest =
          Functional.span(numbers, isEven);
      Integer[] evenSpan = evenSpan_rest.a, rest = evenSpan.rest.b;
      System.out.format("Even span: %s\nRest: %s\n",
          Functional.join(evenSpan, ", "), Functional.join(rest, ", "));
  

(see join(Object[], String)) The output should be:

      Even span: 2, 4, 6
      Rest: 7, 8, 9, 10
  

Type Parameters:

T - The element type of the array.

Parameters:

arr - The array to split.

pred - The predicate to apply.

Returns:

Pair.of(tgt1, tgt2), as a convenience.

span

public static <T,C extends Collection<T>> Pair<T[],T[]> span(C coll,
                                                             Predicate<T> pred)

Split a collection at the first element not satisfying a predicate, returning two arrays.

See span(Object[], Predicate, Collection, Collection) for an example.

Type Parameters:

T - The element type of the collection.

C - The collection type.

Parameters:

coll - The collection to split.

pred - The predicate to apply.

Returns:

Pair.of(tgt1, tgt2), as a convenience.

span

public static <T,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2> span(T[] arr,
                                                                                     Predicate<T> pred,
                                                                                     C1 tgt1,
                                                                                     C2 tgt2)

Split an array at the first element not satisfying a predicate.

For example, given the predicate isEven in the example from Predicate:

      List<Integer> evenSpan, rest;
      Integer[] numbers = { 2, 4, 6, 7, 8, 9, 10 };
      evenSpan = new ArrayList<Integer>();
      rest = new ArrayList<Integer>();
      Functional.span(numbers, isEven, evenSpan, rest);
      System.out.format("Even span: %s\nRest: %s\n", evenSpan, rest);
  

The output should be:

      Even span: [2, 4, 6]
      Rest: [7, 8, 9, 10]
  

Type Parameters:

T - The element type of the array.

C1 - The type of the first target collection.

C2 - The type of the second target collection.

Parameters:

arr - The array to split.

pred - The predicate to apply.

tgt1 - The collection receiving the initial sublist of elements satisfying the predicate.

tgt2 - The collection receiving the rest.

Returns:

Pair.of(tgt1, tgt2), as a convenience.

span

public static <T,C extends Collection<T>,C1 extends Collection<T>,C2 extends Collection<T>> Pair<C1,C2> span(C coll,
                                                                                                             Predicate<T> pred,
                                                                                                             C1 tgt1,
                                                                                                             C2 tgt2)

Split a collection at the first element not satisfying a predicate.

See span(Object[], Predicate, Collection, Collection) for an example.

Type Parameters:

T - The element type of the collection.

C - The collection type.

C1 - The type of the first target collection.

C2 - The type of the second target collection.

Parameters:

coll - The collection to split.

pred - The predicate to apply.

tgt1 - The collection receiving the initial sublist of elements satisfying the predicate.

tgt2 - The collection receiving the rest.

Returns:

Pair.of(tgt1, tgt2), as a convenience.