## org.apache.commons.collections
Class CollectionUtils

    java.lang.Object
      org.apache.commons.collections.CollectionUtils

    public class CollectionUtils

extends java.lang.Object

Provides utility methods and decorators for `Collection` instances.

Since:
  Commons Collections 1.0
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
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 java.util.Collection` `EMPTY_COLLECTION` An empty unmodifiable collection.

Constructor Summary
`CollectionUtils()` `CollectionUtils` should not normally be instantiated.

Method Summary
`static void` `addAll(java.util.Collection collection, java.util.Enumeration enumeration)` Adds all elements in the enumeration to the given collection.
`static void` `addAll(java.util.Collection collection, java.util.Iterator iterator)` Adds all elements in the iteration to the given collection.
`static void` `addAll(java.util.Collection collection, java.lang.Object[] elements)` Adds all elements in the array to the given collection.
`static boolean` `addIgnoreNull(java.util.Collection collection, java.lang.Object object)` Adds an element to the collection unless the element is null.
`static int` `cardinality(java.lang.Object obj, java.util.Collection coll)` Returns the number of occurrences of obj in coll.
`static java.util.Collection` `collect(java.util.Collection inputCollection, Transformer transformer)` Returns a new Collection consisting of the elements of inputCollection transformed by the given transformer.
`static java.util.Collection` `collect(java.util.Collection inputCollection, Transformer transformer, java.util.Collection outputCollection)` Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.
`static java.util.Collection` `collect(java.util.Iterator inputIterator, Transformer transformer)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
`static java.util.Collection` `collect(java.util.Iterator inputIterator, Transformer transformer, java.util.Collection outputCollection)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
`static boolean` `containsAny(java.util.Collection coll1, java.util.Collection coll2)` Returns `true` iff at least one element is in both collections.
`static int` `countMatches(java.util.Collection inputCollection, Predicate predicate)` Counts the number of elements in the input collection that match the predicate.
`static java.util.Collection` `disjunction(java.util.Collection a, java.util.Collection b)` Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Collection`s.
`static boolean` `exists(java.util.Collection collection, Predicate predicate)` Answers true if a predicate is true for at least one element of a collection.
`static void` `filter(java.util.Collection collection, Predicate predicate)` Filter the collection by applying a Predicate to each element.
`static java.lang.Object` `find(java.util.Collection collection, Predicate predicate)` Finds the first element in the given collection which matches the given predicate.
`static void` `forAllDo(java.util.Collection collection, Closure closure)` Executes the given closure on each element in the collection.
`static java.lang.Object` `get(java.lang.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 java.util.Map` `getCardinalityMap(java.util.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 java.lang.Object` `index(java.lang.Object obj, int idx)` Deprecated. use `get(Object, int)` instead. Will be removed in v4.0
`static java.lang.Object` `index(java.lang.Object obj, java.lang.Object index)` Deprecated. use `get(Object, int)` instead. Will be removed in v4.0
`static java.util.Collection` `intersection(java.util.Collection a, java.util.Collection b)` Returns a `Collection` containing the intersection of the given `Collection`s.
`static boolean` `isEmpty(java.util.Collection coll)` Null-safe check if the specified collection is empty.
`static boolean` `isEqualCollection(java.util.Collection a, java.util.Collection b)` Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinalities.
`static boolean` `isFull(java.util.Collection coll)` Returns true if no more elements can be added to the Collection.
`static boolean` `isNotEmpty(java.util.Collection coll)` Null-safe check if the specified collection is not empty.
`static boolean` `isProperSubCollection(java.util.Collection a, java.util.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 boolean` `isSubCollection(java.util.Collection a, java.util.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 int` `maxSize(java.util.Collection coll)` Get the maximum number of elements that the Collection can contain.
`static java.util.Collection` `predicatedCollection(java.util.Collection collection, Predicate predicate)` Returns a predicated (validating) collection backed by the given collection.
`static java.util.Collection` `removeAll(java.util.Collection collection, java.util.Collection remove)` Removes the elements in `remove` from `collection`.
`static java.util.Collection` `retainAll(java.util.Collection collection, java.util.Collection retain)` Returns a collection containing all the elements in `collection` that are also in `retain`.
`static void` `reverseArray(java.lang.Object[] array)` Reverses the order of the given array.
`static java.util.Collection` `select(java.util.Collection inputCollection, Predicate predicate)` Selects all elements from input collection which match the given predicate into an output collection.
`static void` `select(java.util.Collection inputCollection, Predicate predicate, java.util.Collection outputCollection)` Selects all elements from input collection which match the given predicate and adds them to outputCollection.
`static java.util.Collection` `selectRejected(java.util.Collection inputCollection, Predicate predicate)` Selects all elements from inputCollection which don't match the given predicate into an output collection.
`static void` `selectRejected(java.util.Collection inputCollection, Predicate predicate, java.util.Collection outputCollection)` Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.
`static int` `size(java.lang.Object object)` Gets the size of the collection/iterator specified.
`static boolean` `sizeIsEmpty(java.lang.Object object)` Checks if the specified collection/array/iterator is empty.
`static java.util.Collection` `subtract(java.util.Collection a, java.util.Collection b)` Returns a new `Collection` containing `a - b`.
`static java.util.Collection` `synchronizedCollection(java.util.Collection collection)` Returns a synchronized collection backed by the given collection.
`static void` `transform(java.util.Collection collection, Transformer transformer)` Transform the collection by applying a Transformer to each element.
`static java.util.Collection` `transformedCollection(java.util.Collection collection, Transformer transformer)` Returns a transformed bag backed by the given collection.
`static java.util.Collection` `typedCollection(java.util.Collection collection, java.lang.Class type)` Returns a typed collection backed by the given collection.
`static java.util.Collection` `union(java.util.Collection a, java.util.Collection b)` Returns a `Collection` containing the union of the given `Collection`s.
`static java.util.Collection` `unmodifiableCollection(java.util.Collection collection)` Returns an unmodifiable collection backed by the given collection.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### EMPTY_COLLECTION

    public static final java.util.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

### union

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

  Returns a `Collection` containing the union of the given `Collection`s.

  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 `Collection`s.

  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(java.util.Collection)`

### intersection

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

  Returns a `Collection` containing the intersection of the given `Collection`s.

  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 `Collection`s.

  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(java.util.Collection)`, `containsAny(java.util.Collection, java.util.Collection)`

### disjunction

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

  Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Collection`s.

  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

### subtract

    public static java.util.Collection subtract(java.util.Collection a,
                                                java.util.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(java.util.Collection)`

### containsAny

    public static boolean containsAny(java.util.Collection coll1,
                                      java.util.Collection coll2)

  Returns `true` iff at least one element is in both collections.

  In other words, this method returns `true` iff the `intersection(java.util.Collection, java.util.Collection)` 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:
    `intersection(java.util.Collection, java.util.Collection)`

### getCardinalityMap

    public static java.util.Map getCardinalityMap(java.util.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

### isSubCollection

    public static boolean isSubCollection(java.util.Collection a,
                                          java.util.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:
    `isProperSubCollection(java.util.Collection, java.util.Collection)`, `Collection.containsAll(java.util.Collection)`

### isProperSubCollection

    public static boolean isProperSubCollection(java.util.Collection a,
                                                java.util.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

  - `a.size()` and `b.size()` represent the total cardinality of a and b, resp.
  - `a.size() < Integer.MAXVALUE`

  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:
    `isSubCollection(java.util.Collection, java.util.Collection)`, `Collection.containsAll(java.util.Collection)`

### isEqualCollection

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

  Returns `true` iff the given `Collection`s 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.

### cardinality

    public static int cardinality(java.lang.Object obj,
                                  java.util.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

### find

    public static java.lang.Object find(java.util.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(java.util.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

### filter

    public static void filter(java.util.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

### transform

    public static void transform(java.util.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

### countMatches

    public static int countMatches(java.util.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

### exists

    public static boolean exists(java.util.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

### select

    public static java.util.Collection select(java.util.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:
    `java.lang.NullPointerException` - if the input collection is null

### select

    public static void select(java.util.Collection inputCollection,
                              Predicate predicate,
                              java.util.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 java.util.Collection selectRejected(java.util.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:
    `java.lang.NullPointerException` - if the input collection is null

### selectRejected

    public static void selectRejected(java.util.Collection inputCollection,
                                      Predicate predicate,
                                      java.util.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

### collect

    public static java.util.Collection collect(java.util.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:
    `java.lang.NullPointerException` - if the input collection is null

### collect

    public static java.util.Collection collect(java.util.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 java.util.Collection collect(java.util.Collection inputCollection,
                                               Transformer transformer,
                                               java.util.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:
    `java.lang.NullPointerException` - if the output collection is null

### collect

    public static java.util.Collection collect(java.util.Iterator inputIterator,
                                               Transformer transformer,
                                               java.util.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:
    `java.lang.NullPointerException` - if the output collection is null

### addIgnoreNull

    public static boolean addIgnoreNull(java.util.Collection collection,
                                        java.lang.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:
    `java.lang.NullPointerException` - if the collection is null
  Since:
    Commons Collections 3.2

### addAll

    public static void addAll(java.util.Collection collection,
                              java.util.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:
    `java.lang.NullPointerException` - if the collection or iterator is null

### addAll

    public static void addAll(java.util.Collection collection,
                              java.util.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:
    `java.lang.NullPointerException` - if the collection or enumeration is null

### addAll

    public static void addAll(java.util.Collection collection,
                              java.lang.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:
    `java.lang.NullPointerException` - if the collection or array is null

### index

    public static java.lang.Object index(java.lang.Object obj,
                                         int idx)

  Deprecated. use `get(Object, int)` instead. Will be removed in v4.0

  Given an Object, and an index, returns the nth value in the object.
  - If obj is a Map, returns the nth value from the keySet iterator, unless the Map contains an Integer key with integer value = idx, in which case the corresponding map entry value is returned. If idx exceeds the number of entries in the map, an empty Iterator is returned.
  - If obj is a List or an array, returns the nth value, throwing IndexOutOfBoundsException, ArrayIndexOutOfBoundsException, resp. if the nth value does not exist.
  - If obj is an iterator, enumeration or Collection, returns the nth value from the iterator, returning an empty Iterator (resp. Enumeration) if the nth value does not exist.
  - Returns the original obj if it is null or not a Collection or Iterator.

  Parameters:
    `obj` - the object to get an index of, may be null
    `idx` - the index to get
  Throws:
    `java.lang.IndexOutOfBoundsException`
    `java.lang.ArrayIndexOutOfBoundsException`

### index

    public static java.lang.Object index(java.lang.Object obj,
                                         java.lang.Object index)

  Deprecated. use `get(Object, int)` 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:
  - If obj is a Map, use the index as a key to get a value. If no match continue.
  - Check key is an Integer. If not, return the object passed in.
  - If obj is a Map, get the nth value from the keySet iterator. If the Map has fewer than n entries, return an empty Iterator.
  - If obj is a List or an array, get the nth value, throwing IndexOutOfBoundsException, ArrayIndexOutOfBoundsException, resp. if the nth value does not exist.
  - If obj is an iterator, enumeration or Collection, get the nth value from the iterator, returning an empty Iterator (resp. Enumeration) if the nth value does not exist.
  - Return the original obj.

  Parameters:
    `obj` - the object to get an index of
    `index` - the index to get
  Returns:
    the object at the specified index
  Throws:
    `java.lang.IndexOutOfBoundsException`
    `java.lang.ArrayIndexOutOfBoundsException`

### get

    public static java.lang.Object get(java.lang.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:

  - Map -- the value returned is the `Map.Entry` in position `index` in the map's `entrySet` iterator, if there is such an entry.
  - List -- this method is equivalent to the list's get method.
  - Array -- the `index`-th array entry is returned, if there is such an entry; otherwise an `IndexOutOfBoundsException` is thrown.
  - Collection -- the value returned is the `index`-th object returned by the collection's default iterator, if there is such an element.
  - Iterator or Enumeration -- the value returned is the `index`-th object in the Iterator/Enumeration, if there is such an element. The Iterator/Enumeration is advanced to `index` (or to the end, if `index` exceeds the number of entries) as a side effect of this method.

  Parameters:
    `object` - the object to get a value from
    `index` - the index to get
  Returns:
    the object at the specified index
  Throws:
    `java.lang.IndexOutOfBoundsException` - if the index is invalid
    `java.lang.IllegalArgumentException` - if the object type is invalid

### size

    public static int size(java.lang.Object object)

  Gets the size of the collection/iterator specified.

  This method can handles objects as follows

  - Collection - the collection size
  - Map - the map size
  - Array - the array size
  - Iterator - the number of elements remaining in the iterator
  - Enumeration - the number of elements remaining in the enumeration

  Parameters:
    `object` - the object to get the size of
  Returns:
    the size of the specified collection
  Throws:
    `java.lang.IllegalArgumentException` - thrown if object is not recognised or null
  Since:
    Commons Collections 3.1

### sizeIsEmpty

    public static boolean sizeIsEmpty(java.lang.Object object)

  Checks if the specified collection/array/iterator is empty.

  This method can handles objects as follows

  - Collection - via collection isEmpty
  - Map - via map isEmpty
  - Array - using array size
  - Iterator - via hasNext
  - Enumeration - via hasMoreElements

  Note: This method is named to avoid clashing with `isEmpty(Collection)`.

  Parameters:
    `object` - the object to get the size of, not null
  Returns:
    true if empty
  Throws:
    `java.lang.IllegalArgumentException` - thrown if object is not recognised or null
  Since:
    Commons Collections 3.2

### isEmpty

    public static boolean isEmpty(java.util.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

### isNotEmpty

    public static boolean isNotEmpty(java.util.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

### reverseArray

    public static void reverseArray(java.lang.Object[] array)

  Reverses the order of the given array.

  Parameters:
    `array` - the array to reverse

### isFull

    public static boolean isFull(java.util.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:
    `java.lang.NullPointerException` - if the collection is null

### maxSize

    public static int maxSize(java.util.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:
    `java.lang.NullPointerException` - if the collection is null

### retainAll

    public static java.util.Collection retainAll(java.util.Collection collection,
                                                 java.util.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:
    `java.lang.NullPointerException` - if either parameter is null
  Since:
    Commons Collections 3.2

### removeAll

    public static java.util.Collection removeAll(java.util.Collection collection,
                                                 java.util.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:
    `java.lang.NullPointerException` - if either parameter is null
  Since:
    Commons Collections 3.2

### synchronizedCollection

    public static java.util.Collection synchronizedCollection(java.util.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:
    `java.lang.IllegalArgumentException` - if the collection is null

### unmodifiableCollection

    public static java.util.Collection unmodifiableCollection(java.util.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:
    `java.lang.IllegalArgumentException` - if the collection is null

### predicatedCollection

    public static java.util.Collection predicatedCollection(java.util.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:
    `java.lang.IllegalArgumentException` - if the Collection is null

### typedCollection

    public static java.util.Collection typedCollection(java.util.Collection collection,
                                                       java.lang.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

### transformedCollection

    public static java.util.Collection transformedCollection(java.util.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:
    `java.lang.IllegalArgumentException` - if the Collection or Transformer is null

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