CollectionUtils

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.

CollectionUtils should not normally be instantiated.

Adds all elements in the iteration to the given collection.

Adds all elements in the array to the given collection.

Adds all elements in the enumeration to the given collection.

Adds an element to the collection unless the element is null.

Returns the number of occurrences of obj in coll.

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.

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.

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.

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.

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

In other words, this method returns true iff the intersection(Collection, Collection) of coll1 and coll2 is not empty.

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

A null collection or predicate matches no elements.

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

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

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

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

A null collection or predicate returns false.

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.

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.

Executes the given closure on each element in the collection.

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

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.

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.

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.

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.

Returns a Collection containing the intersection of the given Collections.

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

Null-safe check if the specified collection is empty.

Null returns true.

Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.

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

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.

Null-safe check if the specified collection is not empty.

Null returns false.

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

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.

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.

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.

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);.

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);.

Reverses the order of the given array.

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.

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

A null predicate matches no elements.

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.

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.

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

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).

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.

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());
     }
 }
 

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.

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.

Returns a typed collection backed by the given collection.

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

Returns a Collection containing the union of the given Collections.

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

Returns an unmodifiable collection backed by the given collection.

This method uses the implementation in the decorators subpackage.