ix.util
Class Collect

java.lang.Object
  ix.util.Collect

public final class Collect
extends java.lang.Object

Collection and Map utilities

See Also:

Fn, Strings, Util

Nested Class Summary

static class

Collect.ShortestFirstComparator A Comparator that orders shorter Collections before longer ones.

Method Summary

static java.util.List	append(java.util.List a, java.util.List b) Returns a new list of the same class as its first argument and that contains the elements of the first list followed by those of the second.
static boolean	areConsistent(java.util.Map m1, java.util.Map m2) Checks whether two maps are consistent.
static boolean	containsEq(java.util.Collection col, java.lang.Object item) Determines whether a collection contains an element == to an object.
static java.util.Collection	difference(java.util.Collection a, java.util.Collection b) Returns a new collection of the same class as its first argument and that contains the elements of the first collection that do not appear in the second.
static java.util.Map	difference(java.util.Map a, java.util.Map b) Returns a map of the same class as its first argument and that contains the entries from the first map that do not appear in the second.
static boolean	elementsMatch(java.util.List list, java.lang.Class... classes) Tests whether each element of the list is an instance of the corresponding class.
static java.lang.String	elementsToString(java.util.Collection c) Returns the toString() representation of the elements of the collection, separated by commas.
static java.lang.String	elementsToString(java.util.Collection c, Function1 f) Returns the toString() representation of the elements of the collection as transformed by the function and separated by commas.
static java.util.List	ensureList(java.util.List list) Ensures that a value is a List object by returning an empty list if the value is null.
static java.util.Map	ensureMap(java.util.Map map) Ensures that a value is a Map object by returning an empty map if the value is null.
static boolean	equalAsSets(java.util.Collection a, java.util.Collection b) Determines whether two collections have the same elements regardless of order.
static boolean	every(java.util.Collection c, Predicate1 p) Tests whether a predicate is true of every element of a collection.
static java.util.Map	extendMap(java.util.Map m, java.util.Collection keys, java.util.Collection values) Adds entries to a map from a collection of keys and a parallel collection of values.
static java.util.Collection	filter(java.util.Collection result, java.util.Collection c, Predicate1 p) Returns the result collection after adding the elements of another collection for which the predicate returned true;
static java.util.Collection	filter(java.util.Collection c, Predicate1 p) Returns a new collection of the same class as the original and containing only the elements for which the predicate returned true;
static java.util.Map	filter(java.util.Map result, java.util.Map m, Predicate2 p) Returns the result map after adding a map's (key, value) entries for which a predicate returns true.
static java.util.Map	filter(java.util.Map m, Predicate2 p) Returns a new map of the same class as the original and containing only the (key, value) entries for which the predicate returned true;
static java.lang.Object	findIf(java.util.Collection col, Predicate1 p) Returns the first element of the collection such that the predicate is true.
static boolean	haveCommonElements(java.util.Collection a, java.util.Collection b) Checks whether two colletions have any elements in common.
static java.util.List	insertBeforeFirst(java.lang.Object target, java.util.List list, java.util.List add) Returns a same-class copy of a list in which a list of additional elements has been inserted before the first occurrence of a specified target element.
static java.util.Collection	intersection(java.util.Collection a, java.util.Collection b) Returns a new collection of the same class as its first argument and that contains the elements that appear in both collections.
static boolean	isEmpty(java.util.Collection c) Returns true iff the collection is either null or empty.
static boolean	isEmpty(java.util.Map m) Returns true iff the Map is either null or empty.
static java.util.Iterator	iterator(java.util.Collection c) Returns the collections's iterator, treating null as an empty list.
static <E> E	lastElement(java.util.List<E> list) Returns the last element of the list, or null if the list is empty.
static <E> java.util.List<E>	makeFixedList(E... elements) Returns a fixed-length list of the specified elements.
static <E> java.util.List<E>	makeList(E... elements) Returns an extendable list of the specified elements.
static java.util.Collection	map(java.util.Collection result, java.util.Collection c, Function1 f) Returns the result collection after adding the values returned by a function applied to each element of another collection.
static java.util.Collection	map(java.util.Collection c, Function1 f) Returns a new collection of the same class as the original and with corresponding elements obtained by calling the specified function.
static java.util.List	powerset(java.util.List elements) Returns the powerset of a List in a nice order.
static <E> E	randomth(java.util.List<E> list, java.util.Random random) Returns a random element of the list.
static boolean	removeAll(java.util.Map a, java.util.Map b) Removes all entries from a map that appear in a second map.
static java.util.List	replaceFirst(java.lang.Object from, java.lang.Object to, java.util.List source) Replaces the first occurrence of an item in a list, returning the modified list.
static boolean	some(java.util.Collection c, Predicate1 p) Tests whether a prediate is true of at least one element of a collection.
static Function1	toFunction(java.util.Map m) Returns a function based on the map.
static java.util.Map	transposeMap(java.util.Map m) Returns a map of the same class as the original but with keys and values exchanged.
static java.util.Collection	union(java.util.Collection a, java.util.Collection b) Returns a new collection of the same class as its first argument and that contains the elements that appear in the first collection plus all elements from the second collection that were not already in the first.
static void	walkTriangle(java.util.List list, Proc walker) Performs "triangle iteration" on a list.

Methods inherited from class java.lang.Object

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

Method Detail

isEmpty

public static final boolean isEmpty(java.util.Collection c)

Returns true iff the collection is either null or empty.

iterator

public static final java.util.Iterator iterator(java.util.Collection c)

Returns the collections's iterator, treating null as an empty list.

ensureList

public static java.util.List ensureList(java.util.List list)

Ensures that a value is a List object by returning an empty list if the value is null.

makeList

public static <E> java.util.List<E> makeList(E... elements)

Returns an extendable list of the specified elements.

makeFixedList

public static <E> java.util.List<E> makeFixedList(E... elements)

Returns a fixed-length list of the specified elements.

lastElement

public static <E> E lastElement(java.util.List<E> list)

Returns the last element of the list, or null if the list is empty.

randomth

public static <E> E randomth(java.util.List<E> list,
                             java.util.Random random)

Returns a random element of the list.

elementsMatch

public static boolean elementsMatch(java.util.List list,
                                    java.lang.Class... classes)

Tests whether each element of the list is an instance of the corresponding class. It also implicitly tests the list's size.

containsEq

public static boolean containsEq(java.util.Collection col,
                                 java.lang.Object item)

Determines whether a collection contains an element == to an object.

Returns:

true if the collection contains an element == to the specified item, and false if it does not.

findIf

public static java.lang.Object findIf(java.util.Collection col,
                                      Predicate1 p)

Returns the first element of the collection such that the predicate is true.

replaceFirst

public static java.util.List replaceFirst(java.lang.Object from,
                                          java.lang.Object to,
                                          java.util.List source)

Replaces the first occurrence of an item in a list, returning the modified list. If the item does not occur, the list is returned unchanged.

equalAsSets

public static boolean equalAsSets(java.util.Collection a,
                                  java.util.Collection b)

Determines whether two collections have the same elements regardless of order.

haveCommonElements

public static boolean haveCommonElements(java.util.Collection a,
                                         java.util.Collection b)

Checks whether two colletions have any elements in common.

For some reason, the Java collections have a containsAll method but no containsAny. This method fills that gap.

intersection

public static java.util.Collection intersection(java.util.Collection a,
                                                java.util.Collection b)

Returns a new collection of the same class as its first argument and that contains the elements that appear in both collections.

union

public static java.util.Collection union(java.util.Collection a,
                                         java.util.Collection b)

Returns a new collection of the same class as its first argument and that contains the elements that appear in the first collection plus all elements from the second collection that were not already in the first.

difference

public static java.util.Collection difference(java.util.Collection a,
                                              java.util.Collection b)

Returns a new collection of the same class as its first argument and that contains the elements of the first collection that do not appear in the second.

append

public static java.util.List append(java.util.List a,
                                    java.util.List b)

Returns a new list of the same class as its first argument and that contains the elements of the first list followed by those of the second.

insertBeforeFirst

public static java.util.List insertBeforeFirst(java.lang.Object target,
                                               java.util.List list,
                                               java.util.List add)

Returns a same-class copy of a list in which a list of additional elements has been inserted before the first occurrence of a specified target element. If the target does not occur in the original list, an IllegalArgumentException is thrown.

Parameters:

target - the item to insert before

list - the list to insert into

add - the elements to insert

map

public static java.util.Collection map(java.util.Collection c,
                                       Function1 f)

Returns a new collection of the same class as the original and with corresponding elements obtained by calling the specified function.

map

public static java.util.Collection map(java.util.Collection result,
                                       java.util.Collection c,
                                       Function1 f)

Returns the result collection after adding the values returned by a function applied to each element of another collection.

some

public static boolean some(java.util.Collection c,
                           Predicate1 p)

Tests whether a prediate is true of at least one element of a collection.

every

public static boolean every(java.util.Collection c,
                            Predicate1 p)

Tests whether a predicate is true of every element of a collection.

filter

public static java.util.Collection filter(java.util.Collection c,
                                          Predicate1 p)

Returns a new collection of the same class as the original and containing only the elements for which the predicate returned true;

filter

public static java.util.Collection filter(java.util.Collection result,
                                          java.util.Collection c,
                                          Predicate1 p)

Returns the result collection after adding the elements of another collection for which the predicate returned true;

elementsToString

public static java.lang.String elementsToString(java.util.Collection c,
                                                Function1 f)

Returns the toString() representation of the elements of the collection as transformed by the function and separated by commas.

elementsToString

public static java.lang.String elementsToString(java.util.Collection c)

Returns the toString() representation of the elements of the collection, separated by commas.

walkTriangle

public static void walkTriangle(java.util.List list,
                                Proc walker)

Performs "triangle iteration" on a list. For each element in the list, the specified 2-argument procedure is called on that element and each element after it in the list.

powerset

public static java.util.List powerset(java.util.List elements)

Returns the powerset of a List in a nice order. For example, for list [a, b, c], the result will be:

  [[], [a], [b], [c], [a, b], [a, c], [b, c], [a, b, c]]
 

isEmpty

public static final boolean isEmpty(java.util.Map m)

Returns true iff the Map is either null or empty.

ensureMap

public static java.util.Map ensureMap(java.util.Map map)

Ensures that a value is a Map object by returning an empty map if the value is null.

areConsistent

public static boolean areConsistent(java.util.Map m1,
                                    java.util.Map m2)

Checks whether two maps are consistent.

Returns:

true iff agree on the values of every key they have in common.

toFunction

public static Function1 toFunction(java.util.Map m)

Returns a function based on the map. This is useful in conjunction with map(Collection, Function1) and similar methods.

extendMap

public static java.util.Map extendMap(java.util.Map m,
                                      java.util.Collection keys,
                                      java.util.Collection values)

Adds entries to a map from a collection of keys and a parallel collection of values.

Throws:

java.lang.IllegalArgumentException - if a key is already present in the Map or appears more than once in the collection of keys.

AssertionFailure - if the key and value collections are of different lengths.

transposeMap

public static java.util.Map transposeMap(java.util.Map m)

Returns a map of the same class as the original but with keys and values exchanged.

difference

public static java.util.Map difference(java.util.Map a,
                                       java.util.Map b)

Returns a map of the same class as its first argument and that contains the entries from the first map that do not appear in the second. This method calls removeAll(Map, Map) on a copy of the first map.

removeAll

public static boolean removeAll(java.util.Map a,
                                java.util.Map b)

Removes all entries from a map that appear in a second map. Returns true if any change was made. Entries count as the same if the second map has an entry for a key and either both values are null or equals regards the values as the same.

filter

public static java.util.Map filter(java.util.Map m,
                                   Predicate2 p)

Returns a new map of the same class as the original and containing only the (key, value) entries for which the predicate returned true;

filter

public static java.util.Map filter(java.util.Map result,
                                   java.util.Map m,
                                   Predicate2 p)

Returns the result map after adding a map's (key, value) entries for which a predicate returns true.