org.apache.commons.collections

Class CollectionUtils

public class CollectionUtils extends Object

Provides utility methods and decorators for Collection instances.

Since: Commons Collections 1.0

Version: $Revision: 348013 $ $Date: 2005-11-21 23:24:45 +0000 (Mon, 21 Nov 2005) $

Author: Rodney Waldhoff Paul Jack Stephen Colebourne Steve Downey Herve Quiroz Peter KoBek Matthew Hawthorne Janek Bogucki Phil Steitz Steven Melzer Jon Schewe Neil O'Toole Stephen Smith

Field Summary
static CollectionEMPTY_COLLECTION
An empty unmodifiable collection.
Constructor Summary
CollectionUtils()
CollectionUtils should not normally be instantiated.
Method Summary
static voidaddAll(Collection collection, Iterator iterator)
Adds all elements in the iteration to the given collection.
static voidaddAll(Collection collection, Enumeration enumeration)
Adds all elements in the enumeration to the given collection.
static voidaddAll(Collection collection, Object[] elements)
Adds all elements in the array to the given collection.
static booleanaddIgnoreNull(Collection collection, Object object)
Adds an element to the collection unless the element is null.
static intcardinality(Object obj, Collection coll)
Returns the number of occurrences of obj in coll.
static Collectioncollect(Collection inputCollection, Transformer transformer)
Returns a new Collection consisting of the elements of inputCollection transformed by the given transformer.
static Collectioncollect(Iterator inputIterator, Transformer transformer)
Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
static Collectioncollect(Collection inputCollection, Transformer transformer, Collection outputCollection)
Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.
static Collectioncollect(Iterator inputIterator, Transformer transformer, Collection outputCollection)
Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
static booleancontainsAny(Collection coll1, Collection coll2)
Returns true iff at least one element is in both collections.
static intcountMatches(Collection inputCollection, Predicate predicate)
Counts the number of elements in the input collection that match the predicate.
static Collectiondisjunction(Collection a, Collection b)
Returns a Collection containing the exclusive disjunction (symmetric difference) of the given Collections.
static booleanexists(Collection collection, Predicate predicate)
Answers true if a predicate is true for at least one element of a collection.
static voidfilter(Collection collection, Predicate predicate)
Filter the collection by applying a Predicate to each element.
static Objectfind(Collection collection, Predicate predicate)
Finds the first element in the given collection which matches the given predicate.
static voidforAllDo(Collection collection, Closure closure)
Executes the given closure on each element in the collection.
static Objectget(Object object, int index)
Returns the index-th value in object, throwing IndexOutOfBoundsException if there is no such element or IllegalArgumentException if object is not an instance of one of the supported types.
static MapgetCardinalityMap(Collection coll)
Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurrences of that element in the Collection.
static Objectindex(Object obj, int idx)
Given an Object, and an index, returns the nth value in the object.
static Objectindex(Object obj, Object index)
Given an Object, and a key (index), returns the value associated with that key in the Object.
static Collectionintersection(Collection a, Collection b)
Returns a Collection containing the intersection of the given Collections.
static booleanisEmpty(Collection coll)
Null-safe check if the specified collection is empty.
static booleanisEqualCollection(Collection a, Collection b)
Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.
static booleanisFull(Collection coll)
Returns true if no more elements can be added to the Collection.
static booleanisNotEmpty(Collection coll)
Null-safe check if the specified collection is not empty.
static booleanisProperSubCollection(Collection a, Collection b)
Returns true iff a is a proper sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a, and there is at least one element f such that the cardinality of f in b is strictly greater than the cardinality of f in a.
static booleanisSubCollection(Collection a, Collection b)
Returns true iff a is a sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a.
static intmaxSize(Collection coll)
Get the maximum number of elements that the Collection can contain.
static CollectionpredicatedCollection(Collection collection, Predicate predicate)
Returns a predicated (validating) collection backed by the given collection.
static CollectionremoveAll(Collection collection, Collection remove)
Removes the elements in remove from collection.
static CollectionretainAll(Collection collection, Collection retain)
Returns a collection containing all the elements in collection that are also in retain.
static voidreverseArray(Object[] array)
Reverses the order of the given array.
static Collectionselect(Collection inputCollection, Predicate predicate)
Selects all elements from input collection which match the given predicate into an output collection.
static voidselect(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from input collection which match the given predicate and adds them to outputCollection.
static CollectionselectRejected(Collection inputCollection, Predicate predicate)
Selects all elements from inputCollection which don't match the given predicate into an output collection.
static voidselectRejected(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.
static intsize(Object object)
Gets the size of the collection/iterator specified.
static booleansizeIsEmpty(Object object)
Checks if the specified collection/array/iterator is empty.
static Collectionsubtract(Collection a, Collection b)
Returns a new Collection containing a - b.
static CollectionsynchronizedCollection(Collection collection)
Returns a synchronized collection backed by the given collection.
static voidtransform(Collection collection, Transformer transformer)
Transform the collection by applying a Transformer to each element.
static CollectiontransformedCollection(Collection collection, Transformer transformer)
Returns a transformed bag backed by the given collection.
static CollectiontypedCollection(Collection collection, Class type)
Returns a typed collection backed by the given collection.
static Collectionunion(Collection a, Collection b)
Returns a Collection containing the union of the given Collections.
static CollectionunmodifiableCollection(Collection collection)
Returns an unmodifiable collection backed by the given collection.

Field Detail

EMPTY_COLLECTION

public static final Collection EMPTY_COLLECTION
An empty unmodifiable collection. The JDK provides empty Set and List implementations which could be used for this purpose. However they could be cast to Set or List which might be undesirable. This implementation only implements Collection.

Constructor Detail

CollectionUtils

public CollectionUtils()
CollectionUtils should not normally be instantiated.

Method Detail

addAll

public static void addAll(Collection collection, Iterator iterator)
Adds all elements in the iteration to the given collection.

Parameters: collection the collection to add to, must not be null iterator the iterator of elements to add, must not be null

Throws: NullPointerException if the collection or iterator is null

addAll

public static void addAll(Collection collection, Enumeration enumeration)
Adds all elements in the enumeration to the given collection.

Parameters: collection the collection to add to, must not be null enumeration the enumeration of elements to add, must not be null

Throws: NullPointerException if the collection or enumeration is null

addAll

public static void addAll(Collection collection, Object[] elements)
Adds all elements in the array to the given collection.

Parameters: collection the collection to add to, must not be null elements the array of elements to add, must not be null

Throws: NullPointerException if the collection or array is null

addIgnoreNull

public static boolean addIgnoreNull(Collection collection, Object object)
Adds an element to the collection unless the element is null.

Parameters: collection the collection to add to, must not be null object the object to add, if null it will not be added

Returns: true if the collection changed

Throws: NullPointerException if the collection is null

Since: Commons Collections 3.2

cardinality

public static int cardinality(Object obj, Collection coll)
Returns the number of occurrences of obj in coll.

Parameters: obj the object to find the cardinality of coll the collection to search

Returns: the the number of occurrences of obj in coll

collect

public static Collection collect(Collection inputCollection, Transformer transformer)
Returns a new Collection consisting of the elements of inputCollection transformed by the given transformer.

If the input transformer is null, the result is an empty list.

Parameters: inputCollection the collection to get the input from, may not be null transformer the transformer to use, may be null

Returns: the transformed result (new list)

Throws: NullPointerException if the input collection is null

collect

public static Collection collect(Iterator inputIterator, Transformer transformer)
Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

If the input iterator or transformer is null, the result is an empty list.

Parameters: inputIterator the iterator to get the input from, may be null transformer the transformer to use, may be null

Returns: the transformed result (new list)

collect

public static Collection collect(Collection inputCollection, Transformer transformer, Collection outputCollection)
Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.

If the input collection or transformer is null, there is no change to the output collection.

Parameters: inputCollection the collection to get the input from, may be null transformer the transformer to use, may be null outputCollection the collection to output into, may not be null

Returns: the outputCollection with the transformed input added

Throws: NullPointerException if the output collection is null

collect

public static Collection collect(Iterator inputIterator, Transformer transformer, Collection outputCollection)
Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

If the input iterator or transformer is null, there is no change to the output collection.

Parameters: inputIterator the iterator to get the input from, may be null transformer the transformer to use, may be null outputCollection the collection to output into, may not be null

Returns: the outputCollection with the transformed input added

Throws: NullPointerException if the output collection is null

containsAny

public static boolean containsAny(Collection coll1, Collection coll2)
Returns true iff at least one element is in both collections.

In other words, this method returns true iff the CollectionUtils of coll1 and coll2 is not empty.

Parameters: coll1 the first collection, must not be null coll2 the first collection, must not be null

Returns: true iff the intersection of the collections is non-empty

Since: 2.1

See Also: CollectionUtils

countMatches

public static int countMatches(Collection inputCollection, Predicate predicate)
Counts the number of elements in the input collection that match the predicate.

A null collection or predicate matches no elements.

Parameters: inputCollection the collection to get the input from, may be null predicate the predicate to use, may be null

Returns: the number of matches for the predicate in the collection

disjunction

public static Collection disjunction(Collection a, Collection b)
Returns a Collection containing the exclusive disjunction (symmetric difference) of the given Collections.

The cardinality of each element e in the returned Collection will be equal to max(cardinality(e,a),cardinality(e,b)) - min(cardinality(e,a),cardinality(e,b)).

This is equivalent to subtract(union(a,b),intersection(a,b)) or union(subtract(a,b),subtract(b,a)).

Parameters: a the first collection, must not be null b the second collection, must not be null

Returns: the symmetric difference of the two collections

exists

public static boolean exists(Collection collection, Predicate predicate)
Answers true if a predicate is true for at least one element of a collection.

A null collection or predicate returns false.

Parameters: collection the collection to get the input from, may be null predicate the predicate to use, may be null

Returns: true if at least one element of the collection matches the predicate

filter

public static void filter(Collection collection, Predicate predicate)
Filter the collection by applying a Predicate to each element. If the predicate returns false, remove the element.

If the input collection or predicate is null, there is no change made.

Parameters: collection the collection to get the input from, may be null predicate the predicate to use as a filter, may be null

find

public static Object find(Collection collection, Predicate predicate)
Finds the first element in the given collection which matches the given predicate.

If the input collection or predicate is null, or no element of the collection matches the predicate, null is returned.

Parameters: collection the collection to search, may be null predicate the predicate to use, may be null

Returns: the first element of the collection which matches the predicate or null if none could be found

forAllDo

public static void forAllDo(Collection collection, Closure closure)
Executes the given closure on each element in the collection.

If the input collection or closure is null, there is no change made.

Parameters: collection the collection to get the input from, may be null closure the closure to perform, may be null

get

public static Object get(Object object, int index)
Returns the index-th value in object, throwing IndexOutOfBoundsException if there is no such element or IllegalArgumentException if object is not an instance of one of the supported types.

The supported types, and associated semantics are:

Parameters: object the object to get a value from index the index to get

Returns: the object at the specified index

Throws: IndexOutOfBoundsException if the index is invalid IllegalArgumentException if the object type is invalid

getCardinalityMap

public static Map getCardinalityMap(Collection coll)
Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurrences of that element in the Collection.

Only those elements present in the collection will appear as keys in the map.

Parameters: coll the collection to get the cardinality map for, must not be null

Returns: the populated cardinality map

index

public static Object index(Object obj, int idx)

Deprecated: use CollectionUtils instead. Will be removed in v4.0

Given an Object, and an index, returns the nth value in the object.

Parameters: obj the object to get an index of, may be null idx the index to get

Throws: IndexOutOfBoundsException ArrayIndexOutOfBoundsException

index

public static Object index(Object obj, Object index)

Deprecated: use CollectionUtils instead. Will be removed in v4.0

Given an Object, and a key (index), returns the value associated with that key in the Object. The following checks are made:

Parameters: obj the object to get an index of index the index to get

Returns: the object at the specified index

Throws: IndexOutOfBoundsException ArrayIndexOutOfBoundsException

intersection

public static Collection intersection(Collection a, Collection b)
Returns a Collection containing the intersection of the given Collections.

The cardinality of each element in the returned Collection will be equal to the minimum of the cardinality of that element in the two given Collections.

Parameters: a the first collection, must not be null b the second collection, must not be null

Returns: the intersection of the two collections

See Also: Collection#retainAll CollectionUtils

isEmpty

public static boolean isEmpty(Collection coll)
Null-safe check if the specified collection is empty.

Null returns true.

Parameters: coll the collection to check, may be null

Returns: true if empty or null

Since: Commons Collections 3.2

isEqualCollection

public static boolean isEqualCollection(Collection a, Collection b)
Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.

That is, iff the cardinality of e in a is equal to the cardinality of e in b, for each element e in a or b.

Parameters: a the first collection, must not be null b the second collection, must not be null

Returns: true iff the collections contain the same elements with the same cardinalities.

isFull

public static boolean isFull(Collection coll)
Returns true if no more elements can be added to the Collection.

This method uses the BoundedCollection interface to determine the full status. If the collection does not implement this interface then false is returned.

The collection does not have to implement this interface directly. If the collection has been decorated using the decorators subpackage then these will be removed to access the BoundedCollection.

Parameters: coll the collection to check

Returns: true if the BoundedCollection is full

Throws: NullPointerException if the collection is null

isNotEmpty

public static boolean isNotEmpty(Collection coll)
Null-safe check if the specified collection is not empty.

Null returns false.

Parameters: coll the collection to check, may be null

Returns: true if non-null and non-empty

Since: Commons Collections 3.2

isProperSubCollection

public static boolean isProperSubCollection(Collection a, Collection b)
Returns true iff a is a proper sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a, and there is at least one element f such that the cardinality of f in b is strictly greater than the cardinality of f in a.

The implementation assumes

Parameters: a the first (sub?) collection, must not be null b the second (super?) collection, must not be null

Returns: true iff a is a proper sub-collection of b

See Also: CollectionUtils Collection#containsAll

isSubCollection

public static boolean isSubCollection(Collection a, Collection b)
Returns true iff a is a sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a.

Parameters: a the first (sub?) collection, must not be null b the second (super?) collection, must not be null

Returns: true iff a is a sub-collection of b

See Also: CollectionUtils Collection#containsAll

maxSize

public static int maxSize(Collection coll)
Get the maximum number of elements that the Collection can contain.

This method uses the BoundedCollection interface to determine the maximum size. If the collection does not implement this interface then -1 is returned.

The collection does not have to implement this interface directly. If the collection has been decorated using the decorators subpackage then these will be removed to access the BoundedCollection.

Parameters: coll the collection to check

Returns: the maximum size of the BoundedCollection, -1 if no maximum size

Throws: NullPointerException if the collection is null

predicatedCollection

public static Collection predicatedCollection(Collection collection, Predicate predicate)
Returns a predicated (validating) collection backed by the given collection.

Only objects that pass the test in the given predicate can be added to the collection. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original collection after invoking this method, as it is a backdoor for adding invalid objects.

Parameters: collection the collection to predicate, must not be null predicate the predicate for the collection, must not be null

Returns: a predicated collection backed by the given collection

Throws: IllegalArgumentException if the Collection is null

removeAll

public static Collection removeAll(Collection collection, Collection remove)
Removes the elements in remove from collection. That is, this method returns a collection containing all the elements in c that are not in remove. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless remove contains e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call collection.removeAll(remove);.

Parameters: collection the collection from which items are removed (in the returned collection) remove the items to be removed from the returned collection

Returns: a Collection containing all the elements of collection except any elements that also occur in remove.

Throws: NullPointerException if either parameter is null

Since: Commons Collections 3.2

retainAll

public static Collection retainAll(Collection collection, Collection retain)
Returns a collection containing all the elements in collection that are also in retain. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless retain does not contain e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call c.retainAll(retain);.

Parameters: collection the collection whose contents are the target of the #retailAll operation retain the collection containing the elements to be retained in the returned collection

Returns: a Collection containing all the elements of collection that occur at least once in retain.

Throws: NullPointerException if either parameter is null

Since: Commons Collections 3.2

reverseArray

public static void reverseArray(Object[] array)
Reverses the order of the given array.

Parameters: array the array to reverse

select

public static Collection select(Collection inputCollection, Predicate predicate)
Selects all elements from input collection which match the given predicate into an output collection.

A null predicate matches no elements.

Parameters: inputCollection the collection to get the input from, may not be null predicate the predicate to use, may be null

Returns: the elements matching the predicate (new list)

Throws: NullPointerException if the input collection is null

select

public static void select(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from input collection which match the given predicate and adds them to outputCollection.

If the input collection or predicate is null, there is no change to the output collection.

Parameters: inputCollection the collection to get the input from, may be null predicate the predicate to use, may be null outputCollection the collection to output into, may not be null

selectRejected

public static Collection selectRejected(Collection inputCollection, Predicate predicate)
Selects all elements from inputCollection which don't match the given predicate into an output collection.

If the input predicate is null, the result is an empty list.

Parameters: inputCollection the collection to get the input from, may not be null predicate the predicate to use, may be null

Returns: the elements not matching the predicate (new list)

Throws: NullPointerException if the input collection is null

selectRejected

public static void selectRejected(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.

If the input predicate is null, no elements are added to outputCollection.

Parameters: inputCollection the collection to get the input from, may be null predicate the predicate to use, may be null outputCollection the collection to output into, may not be null

size

public static int size(Object object)
Gets the size of the collection/iterator specified.

This method can handles objects as follows

Parameters: object the object to get the size of

Returns: the size of the specified collection

Throws: IllegalArgumentException thrown if object is not recognised or null

Since: Commons Collections 3.1

sizeIsEmpty

public static boolean sizeIsEmpty(Object object)
Checks if the specified collection/array/iterator is empty.

This method can handles objects as follows

Note: This method is named to avoid clashing with isEmpty.

Parameters: object the object to get the size of, not null

Returns: true if empty

Throws: IllegalArgumentException thrown if object is not recognised or null

Since: Commons Collections 3.2

subtract

public static Collection subtract(Collection a, Collection b)
Returns a new Collection containing a - b. The cardinality of each element e in the returned Collection will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.

Parameters: a the collection to subtract from, must not be null b the collection to subtract, must not be null

Returns: a new collection with the results

See Also: Collection#removeAll

synchronizedCollection

public static Collection synchronizedCollection(Collection collection)
Returns a synchronized collection backed by the given collection.

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Collection c = CollectionUtils.synchronizedCollection(myCollection);
 synchronized (c) {
     Iterator i = c.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 
This method uses the implementation in the decorators subpackage.

Parameters: collection the collection to synchronize, must not be null

Returns: a synchronized collection backed by the given collection

Throws: IllegalArgumentException if the collection is null

transform

public static void transform(Collection collection, Transformer transformer)
Transform the collection by applying a Transformer to each element.

If the input collection or transformer is null, there is no change made.

This routine is best for Lists, for which set() is used to do the transformations "in place." For other Collections, clear() and addAll() are used to replace elements.

If the input collection controls its input, such as a Set, and the Transformer creates duplicates (or are otherwise invalid), the collection may reduce in size due to calling this method.

Parameters: collection the collection to get the input from, may be null transformer the transformer to perform, may be null

transformedCollection

public static Collection transformedCollection(Collection collection, Transformer transformer)
Returns a transformed bag backed by the given collection.

Each object is passed through the transformer as it is added to the Collection. It is important not to use the original collection after invoking this method, as it is a backdoor for adding untransformed objects.

Parameters: collection the collection to predicate, must not be null transformer the transformer for the collection, must not be null

Returns: a transformed collection backed by the given collection

Throws: IllegalArgumentException if the Collection or Transformer is null

typedCollection

public static Collection typedCollection(Collection collection, Class type)
Returns a typed collection backed by the given collection.

Only objects of the specified type can be added to the collection.

Parameters: collection the collection to limit to a specific type, must not be null type the type of objects which may be added to the collection

Returns: a typed collection backed by the specified collection

union

public static Collection union(Collection a, Collection b)
Returns a Collection containing the union of the given Collections.

The cardinality of each element in the returned Collection will be equal to the maximum of the cardinality of that element in the two given Collections.

Parameters: a the first collection, must not be null b the second collection, must not be null

Returns: the union of the two collections

See Also: Collection#addAll

unmodifiableCollection

public static Collection unmodifiableCollection(Collection collection)
Returns an unmodifiable collection backed by the given collection.

This method uses the implementation in the decorators subpackage.

Parameters: collection the collection to make unmodifiable, must not be null

Returns: an unmodifiable collection backed by the given collection

Throws: IllegalArgumentException if the collection is null

Copyright © 2001-2008 Apache Software Foundation. All Rights Reserved.