org.apache.commons.collections
public class CollectionUtils extends Object
Since: Commons Collections 1.0
Version: $Revision: 348013 $ $Date: 2005-11-21 23:24:45 +0000 (Mon, 21 Nov 2005) $
Field Summary | |
---|---|
static Collection | EMPTY_COLLECTION
An empty unmodifiable collection.
|
Constructor Summary | |
---|---|
CollectionUtils()CollectionUtils should not normally be instantiated. |
Method Summary | |
---|---|
static void | addAll(Collection collection, Iterator iterator)
Adds all elements in the iteration to the given collection.
|
static void | addAll(Collection collection, Enumeration enumeration)
Adds all elements in the enumeration to the given collection.
|
static void | addAll(Collection collection, Object[] elements)
Adds all elements in the array to the given collection.
|
static boolean | addIgnoreNull(Collection collection, Object object)
Adds an element to the collection unless the element is null.
|
static int | cardinality(Object obj, Collection coll)
Returns the number of occurrences of obj in coll.
|
static Collection | collect(Collection inputCollection, Transformer transformer)
Returns a new Collection consisting of the elements of inputCollection transformed
by the given transformer.
|
static Collection | collect(Iterator inputIterator, Transformer transformer)
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
|
static Collection | collect(Collection inputCollection, Transformer transformer, Collection outputCollection)
Transforms all elements from inputCollection with the given transformer
and adds them to the outputCollection.
|
static Collection | collect(Iterator inputIterator, Transformer transformer, Collection outputCollection)
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
|
static boolean | containsAny(Collection coll1, Collection coll2)
Returns true iff at least one element is in both collections.
|
static int | countMatches(Collection inputCollection, Predicate predicate)
Counts the number of elements in the input collection that match the predicate.
|
static Collection | disjunction(Collection a, Collection b)
Returns a Collection containing the exclusive disjunction
(symmetric difference) of the given Collections.
|
static boolean | exists(Collection collection, Predicate predicate)
Answers true if a predicate is true for at least one element of a collection.
|
static void | filter(Collection collection, Predicate predicate)
Filter the collection by applying a Predicate to each element. |
static Object | find(Collection collection, Predicate predicate)
Finds the first element in the given collection which matches the given predicate.
|
static void | forAllDo(Collection collection, Closure closure)
Executes the given closure on each element in the collection.
|
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 Map | getCardinalityMap(Collection coll)
Returns a Map mapping each unique element in the given
Collection to an Integer representing the number
of occurrences of that element in the Collection.
|
static Object | index(Object obj, int idx)
Given an Object, and an index, returns the nth value in the
object.
|
static Object | index(Object obj, Object index)
Given an Object, and a key (index), returns the value associated with
that key in the Object. |
static Collection | intersection(Collection a, Collection b)
Returns a Collection containing the intersection
of the given Collections.
|
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 Collections contain
exactly the same elements with exactly the same cardinalities.
|
static boolean | isFull(Collection 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 int | maxSize(Collection coll)
Get the maximum number of elements that the Collection can contain.
|
static Collection | predicatedCollection(Collection collection, Predicate predicate)
Returns a predicated (validating) collection backed by the given collection.
|
static Collection | removeAll(Collection collection, Collection remove)
Removes the elements in remove from collection . |
static Collection | retainAll(Collection 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 Collection | select(Collection inputCollection, Predicate predicate)
Selects all elements from input collection which match the given predicate
into an output collection.
|
static void | select(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from input collection which match the given predicate
and adds them to outputCollection.
|
static Collection | selectRejected(Collection inputCollection, Predicate predicate)
Selects all elements from inputCollection which don't match the given predicate
into an output collection.
|
static void | selectRejected(Collection inputCollection, Predicate predicate, Collection outputCollection)
Selects all elements from inputCollection which don't match the given predicate
and adds them to outputCollection.
|
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 Collection | subtract(Collection a, Collection b)
Returns a new Collection containing a - b.
|
static Collection | synchronizedCollection(Collection collection)
Returns a synchronized collection backed by the given collection.
|
static void | transform(Collection collection, Transformer transformer)
Transform the collection by applying a Transformer to each element.
|
static Collection | transformedCollection(Collection collection, Transformer transformer)
Returns a transformed bag backed by the given collection.
|
static Collection | typedCollection(Collection collection, Class type)
Returns a typed collection backed by the given collection.
|
static Collection | union(Collection a, Collection b)
Returns a Collection containing the union
of the given Collections.
|
static Collection | unmodifiableCollection(Collection collection)
Returns an unmodifiable collection backed by the given collection.
|
CollectionUtils
should not normally be instantiated.Parameters: collection the collection to add to, must not be null iterator the iterator of elements to add, must not be null
Throws: NullPointerException if the collection or iterator is null
Parameters: collection the collection to add to, must not be null enumeration the enumeration of elements to add, must not be null
Throws: NullPointerException if the collection or enumeration is null
Parameters: collection the collection to add to, must not be null elements the array of elements to add, must not be null
Throws: NullPointerException if the collection or array is null
Parameters: collection the collection to add to, must not be null object the object to add, if null it will not be added
Returns: true if the collection changed
Throws: NullPointerException if the collection is null
Since: Commons Collections 3.2
Parameters: obj the object to find the cardinality of coll the collection to search
Returns: the the number of occurrences of obj in coll
If the input transformer is null, the result is an empty list.
Parameters: inputCollection the collection to get the input from, may not be null transformer the transformer to use, may be null
Returns: the transformed result (new list)
Throws: NullPointerException if the input collection is null
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)
If the input collection or transformer is null, there is no change to the output collection.
Parameters: inputCollection the collection to get the input from, may be null transformer the transformer to use, may be null outputCollection the collection to output into, may not be null
Returns: the outputCollection with the transformed input added
Throws: NullPointerException if the output collection is null
If the input iterator or transformer is null, there is no change to the output collection.
Parameters: inputIterator the iterator to get the input from, may be null transformer the transformer to use, may be null outputCollection the collection to output into, may not be null
Returns: the outputCollection with the transformed input added
Throws: NullPointerException if the output collection is null
true
iff at least one element is in both collections.
In other words, this method returns true
iff the
CollectionUtils of coll1 and coll2 is not empty.
Parameters: coll1 the first collection, must not be null coll2 the first collection, must not be null
Returns: true
iff the intersection of the collections is non-empty
Since: 2.1
See Also: CollectionUtils
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
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
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
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
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
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
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.Entry
in position
index
in the map's entrySet
iterator,
if there is such an entry.index
-th array entry is returned,
if there is such an entry; otherwise an IndexOutOfBoundsException
is thrown.index
-th object
returned by the collection's default iterator, if there is such an element.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
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
Deprecated: use CollectionUtils instead. Will be removed in v4.0
Given an Object, and an index, returns the nth value in the object.Parameters: obj the object to get an index of, may be null idx the index to get
Throws: IndexOutOfBoundsException ArrayIndexOutOfBoundsException
Deprecated: use CollectionUtils instead. Will be removed in v4.0
Given an Object, and a key (index), returns the value associated with that key in the Object. The following checks are made:Parameters: obj the object to get an index of index the index to get
Returns: the object at the specified index
Throws: IndexOutOfBoundsException ArrayIndexOutOfBoundsException
The cardinality of each element in the returned Collection will be equal to the minimum of the cardinality of that element in the two given Collections.
Parameters: a the first collection, must not be null b the second collection, must not be null
Returns: the intersection of the two collections
See Also: Collection#retainAll CollectionUtils
Null returns true.
Parameters: coll the collection to check, may be null
Returns: true if empty or null
Since: Commons Collections 3.2
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.
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
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
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: CollectionUtils Collection#containsAll
Parameters: a the first (sub?) collection, must not be null b the second (super?) collection, must not be null
Returns: true
iff a is a sub-collection of b
See Also: CollectionUtils Collection#containsAll
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
Only objects that pass the test in the given predicate can be added to the collection. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original collection after invoking this method, as it is a backdoor for adding invalid objects.
Parameters: collection the collection to predicate, must not be null predicate the predicate for the collection, must not be null
Returns: a predicated collection backed by the given collection
Throws: IllegalArgumentException if the Collection is null
remove
from collection
. That is, this
method returns a collection containing all the elements in c
that are not in remove
. The cardinality of an element e
in the returned collection is the same as the cardinality of e
in collection
unless remove
contains e
, in which
case the cardinality is zero. This method is useful if you do not wish to modify
the collection c
and thus cannot call collection.removeAll(remove);
.
Parameters: collection the collection from which items are removed (in the returned collection) remove the items to be removed from the returned collection
Returns: a Collection
containing all the elements of collection
except
any elements that also occur in remove
.
Throws: NullPointerException if either parameter is null
Since: Commons Collections 3.2
collection
that are also in retain
. The cardinality of an element e
in the returned collection is the same as the cardinality of e
in collection
unless retain
does not contain e
, in which
case the cardinality is zero. This method is useful if you do not wish to modify
the collection c
and thus cannot call c.retainAll(retain);
.
Parameters: collection the collection whose contents are the target of the #retailAll operation retain the collection containing the elements to be retained in the returned collection
Returns: a Collection
containing all the elements of collection
that occur at least once in retain
.
Throws: NullPointerException if either parameter is null
Since: Commons Collections 3.2
Parameters: array the array to reverse
A null
predicate matches no elements.
Parameters: inputCollection the collection to get the input from, may not be null predicate the predicate to use, may be null
Returns: the elements matching the predicate (new list)
Throws: NullPointerException if the input collection is null
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
If the input predicate is null
, the result is an empty list.
Parameters: inputCollection the collection to get the input from, may not be null predicate the predicate to use, may be null
Returns: the elements not matching the predicate (new list)
Throws: NullPointerException if the input collection is null
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
This method can handles objects as follows
Parameters: object the object to get the size of
Returns: the size of the specified collection
Throws: IllegalArgumentException thrown if object is not recognised or null
Since: Commons Collections 3.1
This method can handles objects as follows
Note: This method is named to avoid clashing with isEmpty.
Parameters: object the object to get the size of, not null
Returns: true if empty
Throws: IllegalArgumentException thrown if object is not recognised or null
Since: Commons Collections 3.2
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
You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:
Collection c = CollectionUtils.synchronizedCollection(myCollection); synchronized (c) { Iterator i = c.iterator(); while (i.hasNext()) { process (i.next()); } }This method uses the implementation in the decorators subpackage.
Parameters: collection the collection to synchronize, must not be null
Returns: a synchronized collection backed by the given collection
Throws: IllegalArgumentException if the collection is null
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
Each object is passed through the transformer as it is added to the Collection. It is important not to use the original collection after invoking this method, as it is a backdoor for adding untransformed objects.
Parameters: collection the collection to predicate, must not be null transformer the transformer for the collection, must not be null
Returns: a transformed collection backed by the given collection
Throws: IllegalArgumentException if the Collection or Transformer is null
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
The cardinality of each element in the returned Collection will be equal to the maximum of the cardinality of that element in the two given Collections.
Parameters: a the first collection, must not be null b the second collection, must not be null
Returns: the union of the two collections
See Also: Collection#addAll
This method uses the implementation in the decorators subpackage.
Parameters: collection the collection to make unmodifiable, must not be null
Returns: an unmodifiable collection backed by the given collection
Throws: IllegalArgumentException if the collection is null