org.apache.commons.collections4

## Class CollectionUtils

- java.lang.Object
- - org.apache.commons.collections4.CollectionUtils

-     public class CollectionUtils
      extends Object

  Provides utility methods and decorators for `Collection` instances.

  NOTE: From 4.0, method parameters will take `Iterable` objects when possible.

  Since:
    1.0
  Version:
    $Id: CollectionUtils.java 1540639 2013-11-11 08:54:12Z tn $

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Collection` | `EMPTY_COLLECTION` An empty unmodifiable collection.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <C> boolean` | `addAll(Collection<C> collection, C[] elements)` Adds all elements in the array to the given collection.
    `static <C> boolean` | `addAll(Collection<C> collection, Enumeration<? extends C> enumeration)` Adds all elements in the enumeration to the given collection.
    `static <C> boolean` | `addAll(Collection<C> collection, Iterable<? extends C> iterable)` Adds all elements in the `Iterable` to the given collection.
    `static <C> boolean` | `addAll(Collection<C> collection, Iterator<? extends C> iterator)` Adds all elements in the iteration to the given collection.
    `static <T> boolean` | `addIgnoreNull(Collection<T> collection, T object)` Adds an element to the collection unless the element is null.
    `static <O> int` | `cardinality(O obj, Iterable<? super O> coll)` Returns the number of occurrences of obj in coll.
    `static <O extends Comparable<? super O>> List<O>` | `collate(Iterable<? extends O> a, Iterable<? extends O> b)` Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
    `static <O extends Comparable<? super O>> List<O>` | `collate(Iterable<? extends O> a, Iterable<? extends O> b, boolean includeDuplicates)` Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
    `static <O> List<O>` | `collate(Iterable<? extends O> a, Iterable<? extends O> b, Comparator<? super O> c)` Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.
    `static <O> List<O>` | `collate(Iterable<? extends O> a, Iterable<? extends O> b, Comparator<? super O> c, boolean includeDuplicates)` Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.
    `static <I,O,R extends Collection<? super O>> R` | `collect(Iterable<? extends I> inputCollection, Transformer<? super I,? extends O> transformer, R outputCollection)` Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.
    `static <I,O> Collection<O>` | `collect(Iterable<I> inputCollection, Transformer<? super I,? extends O> transformer)` Returns a new Collection consisting of the elements of inputCollection transformed by the given transformer.
    `static <I,O,R extends Collection<? super O>> R` | `collect(Iterator<? extends I> inputIterator, Transformer<? super I,? extends O> transformer, R outputCollection)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
    `static <I,O> Collection<O>` | `collect(Iterator<I> inputIterator, Transformer<? super I,? extends O> transformer)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
    `static boolean` | `containsAll(Collection<?> coll1, Collection<?> coll2)` Returns `true` iff all elements of `coll2` are also contained in `coll1`.
    `static boolean` | `containsAny(Collection<?> coll1, Collection<?> coll2)` Returns `true` iff at least one element is in both collections.
    `static <C> int` | `countMatches(Iterable<C> input, Predicate<? super C> predicate)` Counts the number of elements in the input collection that match the predicate.
    `static <O> Collection<O>` | `disjunction(Iterable<? extends O> a, Iterable<? extends O> b)` Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Iterable`s.
    `static <T> Collection<T>` | `emptyCollection()` Returns the immutable EMPTY_COLLECTION with generic type safety.
    `static <T> Collection<T>` | `emptyIfNull(Collection<T> collection)` Returns an immutable empty collection if the argument is `null`, or the argument itself otherwise.
    `static <C> boolean` | `exists(Iterable<C> input, Predicate<? super C> predicate)` Answers true if a predicate is true for at least one element of a collection.
    `static <E> E` | `extractSingleton(Collection<E> collection)` Extract the lone element of the specified Collection.
    `static <T> boolean` | `filter(Iterable<T> collection, Predicate<? super T> predicate)` Filter the collection by applying a Predicate to each element.
    `static <T> boolean` | `filterInverse(Iterable<T> collection, Predicate<? super T> predicate)` Filter the collection by applying a Predicate to each element.
    `static <T> T` | `find(Iterable<T> collection, Predicate<? super T> predicate)` Finds the first element in the given collection which matches the given predicate.
    `static <T,C extends Closure<? super T>> T` | `forAllButLastDo(Iterable<T> collection, C closure)` Executes the given closure on each but the last element in the collection.
    `static <T,C extends Closure<? super T>> T` | `forAllButLastDo(Iterator<T> iterator, C closure)` Executes the given closure on each but the last element in the collection.
    `static <T,C extends Closure<? super T>> C` | `forAllDo(Iterable<T> collection, C closure)` Executes the given closure on each element in the collection.
    `static <T,C extends Closure<? super T>> C` | `forAllDo(Iterator<T> iterator, C closure)` Executes the given closure on each element in the collection.
    `static <T> T` | `get(Iterable<T> iterable, int index)` Returns the `index`-th value in the `iterable`'s `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.
    `static <T> T` | `get(Iterator<T> iterator, int index)` Returns the `index`-th value in `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.
    `static <K,V> Map.Entry<K,V>` | `get(Map<K,V> map, int index)` Returns the `index`-th `Map.Entry` in the `map`'s `entrySet`, throwing `IndexOutOfBoundsException` if there is no such element.
    `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.
    `static <O> Map<O,Integer>` | `getCardinalityMap(Iterable<? extends O> 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 <O> Collection<O>` | `intersection(Iterable<? extends O> a, Iterable<? extends O> b)` Returns a `Collection` containing the intersection of the given `Iterable`s.
    `static boolean` | `isEmpty(Collection<?> coll)` Null-safe check if the specified collection is empty.
    `static boolean` | `isEqualCollection(Collection<?> a, Collection<?> b)` Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinalities.
    `static boolean` | `isEqualCollection(Collection<?> a, Collection<?> b, Equator<?> equator)` Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinalities.
    `static boolean` | `isFull(Collection<? extends Object> coll)` Returns true if no more elements can be added to the Collection.
    `static boolean` | `isNotEmpty(Collection<?> coll)` Null-safe check if the specified collection is not empty.
    `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.
    `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.
    `static <C> boolean` | `matchesAll(Iterable<C> input, Predicate<? super C> predicate)` Answers true if a predicate is true for every element of a collection.
    `static int` | `maxSize(Collection<? extends Object> coll)` Get the maximum number of elements that the Collection can contain.
    `static <E> Collection<List<E>>` | `permutations(Collection<E> collection)` Returns a `Collection` of all the permutations of the input collection.
    `static <C> Collection<C>` | `predicatedCollection(Collection<C> collection, Predicate<? super C> predicate)` Returns a predicated (validating) collection backed by the given collection.
    `static <E> Collection<E>` | `removeAll(Collection<E> collection, Collection<?> remove)` Removes the elements in `remove` from `collection`.
    `static <C> Collection<C>` | `retainAll(Collection<C> collection, Collection<?> retain)` Returns a collection containing all the elements in `collection` that are also in `retain`.
    `static void` | `reverseArray(Object[] array)` Reverses the order of the given array.
    `static <O> Collection<O>` | `select(Iterable<? extends O> inputCollection, Predicate<? super O> predicate)` Selects all elements from input collection which match the given predicate into an output collection.
    `static <O,R extends Collection<? super O>> R` | `select(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection)` Selects all elements from input collection which match the given predicate and adds them to outputCollection.
    `static <O> Collection<O>` | `selectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate)` Selects all elements from inputCollection which don't match the given predicate into an output collection.
    `static <O,R extends Collection<? super O>> R` | `selectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection)` Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.
    `static int` | `size(Object object)` Gets the size of the collection/iterator specified.
    `static boolean` | `sizeIsEmpty(Object object)` Checks if the specified collection/array/iterator is empty.
    `static <O> Collection<O>` | `subtract(Iterable<? extends O> a, Iterable<? extends O> b)` Returns a new `Collection` containing `a - b`.
    `static <O> Collection<O>` | `subtract(Iterable<? extends O> a, Iterable<? extends O> b, Predicate<O> p)` Returns a new `Collection` containing a minus a subset of b.
    `static <C> Collection<C>` | `synchronizedCollection(Collection<C> collection)` Returns a synchronized collection backed by the given collection.
    `static <C> void` | `transform(Collection<C> collection, Transformer<? super C,? extends C> transformer)` Transform the collection by applying a Transformer to each element.
    `static <E> Collection<E>` | `transformingCollection(Collection<E> collection, Transformer<? super E,? extends E> transformer)` Returns a transformed bag backed by the given collection.
    `static <O> Collection<O>` | `union(Iterable<? extends O> a, Iterable<? extends O> b)` Returns a `Collection` containing the union of the given `Iterable`s.
    `static <C> Collection<C>` | `unmodifiableCollection(Collection<? extends C> 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 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.

  - ### Method Detail

    - #### emptyCollection

          public static <T> Collection<T> emptyCollection()

      Returns the immutable EMPTY_COLLECTION with generic type safety.
      Type Parameters:
        `T` - the element type
      Returns:
        immutable empty collection
      Since:
        4.0
      See Also:
        `EMPTY_COLLECTION`

    - #### emptyIfNull

          public static <T> Collection<T> emptyIfNull(Collection<T> collection)

      Returns an immutable empty collection if the argument is `null`, or the argument itself otherwise.
      Type Parameters:
        `T` - the element type
      Parameters:
        `collection` - the collection, possibly `null`
      Returns:
        an empty collection if the argument is `null`

    - #### union

          public static <O> Collection<O> union(Iterable<? extends O> a,
                                Iterable<? extends O> b)

      Returns a `Collection` containing the union of the given `Iterable`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 `Iterable`s.

      Type Parameters:
        `O` - the generic type that is able to represent the types contained in both input 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(java.util.Collection<? extends E>)`

    - #### intersection

          public static <O> Collection<O> intersection(Iterable<? extends O> a,
                                       Iterable<? extends O> b)

      Returns a `Collection` containing the intersection of the given `Iterable`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 `Iterable`s.

      Type Parameters:
        `O` - the generic type that is able to represent the types contained in both input 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(java.util.Collection<?>)`, `containsAny(java.util.Collection<?>, java.util.Collection<?>)`

    - #### disjunction

          public static <O> Collection<O> disjunction(Iterable<? extends O> a,
                                      Iterable<? extends O> b)

      Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Iterable`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)`)`.

      Type Parameters:
        `O` - the generic type that is able to represent the types contained in both input collections.
      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 <O> Collection<O> subtract(Iterable<? extends O> a,
                                   Iterable<? extends O> 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.
      Type Parameters:
        `O` - the generic type that is able to represent the types contained in both input collections.
      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<?>)`

    - #### subtract

          public static <O> Collection<O> subtract(Iterable<? extends O> a,
                                   Iterable<? extends O> b,
                                   Predicate<O> p)

      Returns a new `Collection` containing a minus a subset of b. Only the elements of b that satisfy the predicate condition, p are subtracted from a.

      The cardinality of each element e in the returned `Collection` that satisfies the predicate condition will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.

      The cardinality of each element e in the returned `Collection` that does not satisfy the predicate condition will be equal to the cardinality of e in a.

      Type Parameters:
        `O` - the generic type that is able to represent the types contained in both input collections.
      Parameters:
        `a` - the collection to subtract from, must not be null
        `b` - the collection to subtract, must not be null
        `p` - the condition used to determine which elements of b are subtracted.
      Returns:
        a new collection with the results
      Since:
        4.0
      See Also:
        `Collection.removeAll(java.util.Collection<?>)`

    - #### containsAll

          public static boolean containsAll(Collection<?> coll1,
                            Collection<?> coll2)

      Returns `true` iff all elements of `coll2` are also contained in `coll1`. The cardinality of values in `coll2` is not taken into account, which is the same behavior as `Collection.containsAll(Collection)`.

      In other words, this method returns `true` iff the `intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)` of coll1 and coll2 has the same cardinality as the set of unique values from `coll2`. In case `coll2` is empty, `true` will be returned.

      This method is intended as a replacement for `Collection.containsAll(Collection)` with a guaranteed runtime complexity of `O(n + m)`. Depending on the type of `Collection` provided, this method will be much faster than calling `Collection.containsAll(Collection)` instead, though this will come at the cost of an additional space complexity O(n).

      Parameters:
        `coll1` - the first collection, must not be null
        `coll2` - the second collection, must not be null
      Returns:
        `true` iff the intersection of the collections has the same cardinality as the set of unique elements from the second collection
      Since:
        4.0

    - #### 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 `intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)` of coll1 and coll2 is not empty.

      Parameters:
        `coll1` - the first collection, must not be null
        `coll2` - the second collection, must not be null
      Returns:
        `true` iff the intersection of the collections is non-empty
      Since:
        2.1
      See Also:
        `intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)`

    - #### getCardinalityMap

          public static <O> Map<O,Integer> getCardinalityMap(Iterable<? extends O> 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.

      Type Parameters:
        `O` - the type of object in the returned `Map`. This is a super type of .
      Parameters:
        `coll` - the collection to get the cardinality map for, must not be null
      Returns:
        the populated cardinality map

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

    - #### 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

      - `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(Collection<?> a,
                                  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.

    - #### isEqualCollection

          public static boolean isEqualCollection(Collection<?> a,
                                  Collection<?> b,
                                  Equator<?> equator)

      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
        `equator` - the Equator used for testing equality
      Returns:
        `true` iff the collections contain the same elements with the same cardinalities.
      Throws:
        `IllegalArgumentException` - if the equator is null
      Since:
        4.0

    - #### cardinality

          public static <O> int cardinality(O obj,
                            Iterable<? super O> coll)

      Returns the number of occurrences of obj in coll.
      Type Parameters:
        `O` - the type of object that the `Iterable` may contain.
      Parameters:
        `obj` - the object to find the cardinality of
        `coll` - the `Iterable` to search
      Returns:
        the the number of occurrences of obj in coll

    - #### find

          public static <T> T find(Iterable<T> collection,
                   Predicate<? super T> 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.

      Type Parameters:
        `T` - the type of object the `Iterable` contains
      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 <T,C extends Closure<? super T>> C forAllDo(Iterable<T> collection,
                                                    C closure)

      Executes the given closure on each element in the collection.

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

      Type Parameters:
        `T` - the type of object the `Iterable` contains
        `C` - the closure type
      Parameters:
        `collection` - the collection to get the input from, may be null
        `closure` - the closure to perform, may be null
      Returns:
        closure

    - #### forAllDo

          public static <T,C extends Closure<? super T>> C forAllDo(Iterator<T> iterator,
                                                    C closure)

      Executes the given closure on each element in the collection.

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

      Type Parameters:
        `T` - the type of object the `Iterator` contains
        `C` - the closure type
      Parameters:
        `iterator` - the iterator to get the input from, may be null
        `closure` - the closure to perform, may be null
      Returns:
        closure
      Since:
        4.0

    - #### forAllButLastDo

          public static <T,C extends Closure<? super T>> T forAllButLastDo(Iterable<T> collection,
                                                           C closure)

      Executes the given closure on each but the last element in the collection.

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

      Type Parameters:
        `T` - the type of object the `Iterable` contains
        `C` - the closure type
      Parameters:
        `collection` - the collection to get the input from, may be null
        `closure` - the closure to perform, may be null
      Returns:
        the last element in the collection, or null if either collection or closure is null
      Since:
        4.0

    - #### forAllButLastDo

          public static <T,C extends Closure<? super T>> T forAllButLastDo(Iterator<T> iterator,
                                                           C closure)

      Executes the given closure on each but the last element in the collection.

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

      Type Parameters:
        `T` - the type of object the `Collection` contains
        `C` - the closure type
      Parameters:
        `iterator` - the iterator to get the input from, may be null
        `closure` - the closure to perform, may be null
      Returns:
        the last element in the collection, or null if either iterator or closure is null
      Since:
        4.0

    - #### filter

          public static <T> boolean filter(Iterable<T> collection,
                           Predicate<? super T> 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.

      Type Parameters:
        `T` - the type of object the `Iterable` contains
      Parameters:
        `collection` - the collection to get the input from, may be null
        `predicate` - the predicate to use as a filter, may be null
      Returns:
        true if the collection is modified by this call, false otherwise.

    - #### filterInverse

          public static <T> boolean filterInverse(Iterable<T> collection,
                                  Predicate<? super T> predicate)

      Filter the collection by applying a Predicate to each element. If the predicate returns true, remove the element.

      This is equivalent to

          filter(collection, PredicateUtils.notPredicate(predicate))

      if predicate is != null.

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

      Type Parameters:
        `T` - the type of object the `Iterable` contains
      Parameters:
        `collection` - the collection to get the input from, may be null
        `predicate` - the predicate to use as a filter, may be null
      Returns:
        true if the collection is modified by this call, false otherwise.

    - #### transform

          public static <C> void transform(Collection<C> collection,
                           Transformer<? super C,? extends C> 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.

      Type Parameters:
        `C` - the type of object the `Collection` contains
      Parameters:
        `collection` - the `Collection` to get the input from, may be null
        `transformer` - the transformer to perform, may be null

    - #### countMatches

          public static <C> int countMatches(Iterable<C> input,
                             Predicate<? super C> predicate)

      Counts the number of elements in the input collection that match the predicate.

      A `null` collection or predicate matches no elements.

      Type Parameters:
        `C` - the type of object the `Iterable` contains
      Parameters:
        `input` - the `Iterable` 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 <C> boolean exists(Iterable<C> input,
                           Predicate<? super C> predicate)

      Answers true if a predicate is true for at least one element of a collection.

      A `null` collection or predicate returns false.

      Type Parameters:
        `C` - the type of object the `Iterable` contains
      Parameters:
        `input` - the `Iterable` 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

    - #### matchesAll

          public static <C> boolean matchesAll(Iterable<C> input,
                               Predicate<? super C> predicate)

      Answers true if a predicate is true for every element of a collection.

      A `null` predicate returns false.
      A `null` or empty collection returns true.

      Type Parameters:
        `C` - the type of object the `Iterable` contains
      Parameters:
        `input` - the `Iterable` to get the input from, may be null
        `predicate` - the predicate to use, may be null
      Returns:
        true if every element of the collection matches the predicate or if the collection is empty, false otherwise
      Since:
        4.0

    - #### select

          public static <O> Collection<O> select(Iterable<? extends O> inputCollection,
                                 Predicate<? super O> predicate)

      Selects all elements from input collection which match the given predicate into an output collection.

      A `null` predicate matches no elements.

      Type Parameters:
        `O` - the type of object the `Iterable` contains
      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 <O,R extends Collection<? super O>> R select(Iterable<? extends O> inputCollection,
                                                     Predicate<? super O> predicate,
                                                     R 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.

      Type Parameters:
        `O` - the type of object the `Iterable` contains
        `R` - the type of 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 if the inputCollection and predicate or not null
      Returns:
        the outputCollection

    - #### selectRejected

          public static <O> Collection<O> selectRejected(Iterable<? extends O> inputCollection,
                                         Predicate<? super O> 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.

      Type Parameters:
        `O` - the type of object the `Iterable` contains
      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 <O,R extends Collection<? super O>> R selectRejected(Iterable<? extends O> inputCollection,
                                                             Predicate<? super O> predicate,
                                                             R 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`.

      Type Parameters:
        `O` - the type of object the `Iterable` contains
        `R` - the type of 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 if the inputCollection and predicate or not null
      Returns:
        outputCollection

    - #### collect

          public static <I,O> Collection<O> collect(Iterable<I> inputCollection,
                                    Transformer<? super I,? extends O> 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.

      Type Parameters:
        `I` - the type of object in the input collection
        `O` - the type of object in the output collection
      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 <I,O> Collection<O> collect(Iterator<I> inputIterator,
                                    Transformer<? super I,? extends O> 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.

      Type Parameters:
        `I` - the type of object in the input collection
        `O` - the type of object in the output collection
      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 <I,O,R extends Collection<? super O>> R collect(Iterable<? extends I> inputCollection,
                                                        Transformer<? super I,? extends O> transformer,
                                                        R 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.

      Type Parameters:
        `I` - the type of object in the input collection
        `O` - the type of object in the output collection
        `R` - the output type of the transformer - this extends O.
      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 if the inputCollection and transformer are not null
      Returns:
        the outputCollection with the transformed input added
      Throws:
        `NullPointerException` - if the output collection is null and both, inputCollection and transformer are not null

    - #### collect

          public static <I,O,R extends Collection<? super O>> R collect(Iterator<? extends I> inputIterator,
                                                        Transformer<? super I,? extends O> transformer,
                                                        R 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.

      Type Parameters:
        `I` - the type of object in the input collection
        `O` - the type of object in the output collection
        `R` - the output type of the transformer - this extends O.
      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 if the inputCollection and transformer are not null
      Returns:
        the outputCollection with the transformed input added
      Throws:
        `NullPointerException` - if the output collection is null and both, inputCollection and transformer are not null

    - #### addIgnoreNull

          public static <T> boolean addIgnoreNull(Collection<T> collection,
                                  T object)

      Adds an element to the collection unless the element is null.
      Type Parameters:
        `T` - the type of object the `Collection` contains
      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:
        3.2

    - #### addAll

          public static <C> boolean addAll(Collection<C> collection,
                           Iterable<? extends C> iterable)

      Adds all elements in the `Iterable` to the given collection. If the `Iterable` is a `Collection` then it is cast and will be added using `Collection.addAll(Collection)` instead of iterating.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      Parameters:
        `collection` - the collection to add to, must not be null
        `iterable` - the iterable of elements to add, must not be null
      Returns:
        a boolean indicating whether the collection has changed or not.
      Throws:
        `NullPointerException` - if the collection or iterator is null

    - #### addAll

          public static <C> boolean addAll(Collection<C> collection,
                           Iterator<? extends C> iterator)

      Adds all elements in the iteration to the given collection.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      Parameters:
        `collection` - the collection to add to, must not be null
        `iterator` - the iterator of elements to add, must not be null
      Returns:
        a boolean indicating whether the collection has changed or not.
      Throws:
        `NullPointerException` - if the collection or iterator is null

    - #### addAll

          public static <C> boolean addAll(Collection<C> collection,
                           Enumeration<? extends C> enumeration)

      Adds all elements in the enumeration to the given collection.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      Parameters:
        `collection` - the collection to add to, must not be null
        `enumeration` - the enumeration of elements to add, must not be null
      Returns:
        `true` if the collections was changed, `false` otherwise
      Throws:
        `NullPointerException` - if the collection or enumeration is null

    - #### addAll

          public static <C> boolean addAll(Collection<C> collection,
                           C[] elements)

      Adds all elements in the array to the given collection.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      Parameters:
        `collection` - the collection to add to, must not be null
        `elements` - the array of elements to add, must not be null
      Returns:
        `true` if the collection was changed, `false` otherwise
      Throws:
        `NullPointerException` - if the collection or array is null

    - #### get

          public static <T> T get(Iterator<T> iterator,
                  int index)

      Returns the `index`-th value in `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

      The Iterator is advanced to `index` (or to the end, if `index` exceeds the number of entries) as a side effect of this method.

      Type Parameters:
        `T` - the type of object in the `Iterator`
      Parameters:
        `iterator` - the iterator 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

    - #### get

          public static <T> T get(Iterable<T> iterable,
                  int index)

      Returns the `index`-th value in the `iterable`'s `Iterator`, throwing `IndexOutOfBoundsException` if there is no such element.

      If the `Iterable` is a `List`, then it will use `List.get(int)`.

      Type Parameters:
        `T` - the type of object in the `Iterable`.
      Parameters:
        `iterable` - the `Iterable` to get a value from
        `index` - the index to get
      Returns:
        the object at the specified index
      Throws:
        `IndexOutOfBoundsException` - if the index is invalid

    - #### 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:

      - 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:
        `IndexOutOfBoundsException` - if the index is invalid
        `IllegalArgumentException` - if the object type is invalid

    - #### get

          public static <K,V> Map.Entry<K,V> get(Map<K,V> map,
                                 int index)

      Returns the `index`-th `Map.Entry` in the `map`'s `entrySet`, throwing `IndexOutOfBoundsException` if there is no such element.
      Type Parameters:
        `K` - the key type in the `Map`
        `V` - the key type in the `Map`
      Parameters:
        `map` - 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

    - #### size

          public static int size(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, may be null
      Returns:
        the size of the specified collection or 0 if the object was null
      Throws:
        `IllegalArgumentException` - thrown if object is not recognised
      Since:
        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

      - 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, may be null
      Returns:
        true if empty or null
      Throws:
        `IllegalArgumentException` - thrown if object is not recognised
      Since:
        3.2

    - #### 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:
        3.2

    - #### 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:
        3.2

    - #### reverseArray

          public static void reverseArray(Object[] array)

      Reverses the order of the given array.
      Parameters:
        `array` - the array to reverse

    - #### isFull

          public static boolean isFull(Collection<? extends Object> 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

    - #### maxSize

          public static int maxSize(Collection<? extends Object> 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

    - #### collate

          public static <O extends Comparable<? super O>> List<O> collate(Iterable<? extends O> a,
                                                          Iterable<? extends O> b)

      Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.

      Uses the standard O(n) merge algorithm for combining two sorted lists.

      Type Parameters:
        `O` - the element type
      Parameters:
        `a` - the first collection, must not be null
        `b` - the second collection, must not be null
      Returns:
        a new sorted List, containing the elements of Collection a and b
      Throws:
        `IllegalArgumentException` - if either collection is null
      Since:
        4.0

    - #### collate

          public static <O extends Comparable<? super O>> List<O> collate(Iterable<? extends O> a,
                                                          Iterable<? extends O> b,
                                                          boolean includeDuplicates)

      Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.

      Uses the standard O(n) merge algorithm for combining two sorted lists.

      Type Parameters:
        `O` - the element type
      Parameters:
        `a` - the first collection, must not be null
        `b` - the second collection, must not be null
        `includeDuplicates` - if `true` duplicate elements will be retained, otherwise they will be removed in the output collection
      Returns:
        a new sorted List, containing the elements of Collection a and b
      Throws:
        `IllegalArgumentException` - if either collection is null
      Since:
        4.0

    - #### collate

          public static <O> List<O> collate(Iterable<? extends O> a,
                            Iterable<? extends O> b,
                            Comparator<? super O> c)

      Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.

      Uses the standard O(n) merge algorithm for combining two sorted lists.

      Type Parameters:
        `O` - the element type
      Parameters:
        `a` - the first collection, must not be null
        `b` - the second collection, must not be null
        `c` - the comparator to use for the merge.
      Returns:
        a new sorted List, containing the elements of Collection a and b
      Throws:
        `IllegalArgumentException` - if either collection or the comparator is null
      Since:
        4.0

    - #### collate

          public static <O> List<O> collate(Iterable<? extends O> a,
                            Iterable<? extends O> b,
                            Comparator<? super O> c,
                            boolean includeDuplicates)

      Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.

      Uses the standard O(n) merge algorithm for combining two sorted lists.

      Type Parameters:
        `O` - the element type
      Parameters:
        `a` - the first collection, must not be null
        `b` - the second collection, must not be null
        `c` - the comparator to use for the merge.
        `includeDuplicates` - if `true` duplicate elements will be retained, otherwise they will be removed in the output collection
      Returns:
        a new sorted List, containing the elements of Collection a and b
      Throws:
        `IllegalArgumentException` - if either collection or the comparator is null
      Since:
        4.0

    - #### permutations

          public static <E> Collection<List<E>> permutations(Collection<E> collection)

      Returns a `Collection` of all the permutations of the input collection.

      NOTE: the number of permutations of a given collection is equal to n!, where n is the size of the collection. Thus, the resulting collection will become very large for collections > 10 (e.g. 10! = 3628800, 15! = 1307674368000).

      For larger collections it is advised to use a `PermutationIterator` to iterate over all permutations.

      Type Parameters:
        `E` - the element type
      Parameters:
        `collection` - the collection to create permutations for, may not be null
      Returns:
        an unordered collection of all permutations of the input collection
      Throws:
        `NullPointerException` - if collection is null
      Since:
        4.0
      See Also:
        `PermutationIterator`

    - #### retainAll

          public static <C> Collection<C> retainAll(Collection<C> 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);`.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      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:
        3.2

    - #### removeAll

          public static <E> Collection<E> removeAll(Collection<E> 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);`.
      Type Parameters:
        `E` - the type of object the `Collection` contains
      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:
        4.0 (method existed in 3.2 but was completely broken)

    - #### synchronizedCollection

          public static <C> Collection<C> synchronizedCollection(Collection<C> 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.
      Type Parameters:
        `C` - the type of object the `Collection` contains
      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

    - #### unmodifiableCollection

          public static <C> Collection<C> unmodifiableCollection(Collection<? extends C> collection)

      Returns an unmodifiable collection backed by the given collection.

      This method uses the implementation in the decorators subpackage.

      Type Parameters:
        `C` - the type of object the `Collection` contains
      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

    - #### predicatedCollection

          public static <C> Collection<C> predicatedCollection(Collection<C> collection,
                                               Predicate<? super C> 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.

      Type Parameters:
        `C` - the type of objects in the Collection.
      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

    - #### transformingCollection

          public static <E> Collection<E> transformingCollection(Collection<E> collection,
                                                 Transformer<? super E,? extends E> 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.

      Existing entries in the specified collection will not be transformed. If you want that behaviour, see `TransformedCollection.transformedCollection(java.util.Collection<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>)`.

      Type Parameters:
        `E` - the type of object the `Collection` contains
      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

    - #### extractSingleton

          public static <E> E extractSingleton(Collection<E> collection)

      Extract the lone element of the specified Collection.
      Type Parameters:
        `E` - collection type
      Parameters:
        `collection` - to read
      Returns:
        sole member of collection
      Throws:
        `IllegalArgumentException` - if collection is null/empty or contains more than one element
      Since:
        4.0

Copyright © 2001–2013 The Apache Software Foundation. All rights reserved.