java.lang.Object | |
↳ | org.apache.commons.collections.CollectionUtils |
Provides utility methods and decorators for Collection instances.
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
EMPTY_COLLECTION | An empty unmodifiable collection. |
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CollectionUtils should not normally be instantiated. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
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.
| |||||||||||
Returns a new Collection consisting of the elements of inputCollection transformed
by the given transformer.
| |||||||||||
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
| |||||||||||
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
| |||||||||||
Returns
true iff at least one element is in both collections. | |||||||||||
Counts the number of elements in the input collection that match the predicate.
| |||||||||||
Returns a
Collection containing the exclusive disjunction
(symmetric difference) of the given Collection s. | |||||||||||
Answers true if a predicate is true for at least one element of a collection.
| |||||||||||
Filter the collection by applying a Predicate to each element.
| |||||||||||
Finds the first element in the given collection which matches the given predicate.
| |||||||||||
Executes the given closure on each element in the collection.
| |||||||||||
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. | |||||||||||
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 . | |||||||||||
This method is deprecated.
use
get(Object, int) instead. Will be removed in v4.0
| |||||||||||
This method is deprecated.
use
get(Object, int) instead. Will be removed in v4.0
| |||||||||||
Returns a
Collection containing the intersection
of the given Collection s. | |||||||||||
Null-safe check if the specified collection is empty.
| |||||||||||
Returns true iff the given
Collection s contain
exactly the same elements with exactly the same cardinalities. | |||||||||||
Returns true if no more elements can be added to the Collection.
| |||||||||||
Null-safe check if the specified collection is not empty.
| |||||||||||
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.
| |||||||||||
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.
| |||||||||||
Returns a predicated (validating) collection backed by the given collection.
| |||||||||||
Removes the elements in
remove from collection . | |||||||||||
Returns a collection containing all the elements in
collection
that are also in retain . | |||||||||||
Reverses the order of the given array.
| |||||||||||
Selects all elements from input collection which match the given predicate
and adds them to outputCollection.
| |||||||||||
Selects all elements from input collection which match the given predicate
into an output collection.
| |||||||||||
Selects all elements from inputCollection which don't match the given predicate
into an output collection.
| |||||||||||
Selects all elements from inputCollection which don't match the given predicate
and adds them to outputCollection.
| |||||||||||
Gets the size of the collection/iterator specified.
| |||||||||||
Checks if the specified collection/array/iterator is empty.
| |||||||||||
Returns a new
Collection containing a - b. | |||||||||||
Returns a synchronized collection backed by the given collection.
| |||||||||||
Transform the collection by applying a Transformer to each element.
| |||||||||||
Returns a transformed bag backed by the given collection.
| |||||||||||
Returns a typed collection backed by the given collection.
| |||||||||||
Returns a
Collection containing the union
of the given Collection s. | |||||||||||
Returns an unmodifiable collection backed by the given collection.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
![]() |
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.
collection | the collection to add to, must not be null |
---|---|
iterator | the iterator of elements to add, must not be null |
NullPointerException | if the collection or iterator is null |
---|
Adds all elements in the array to the given collection.
collection | the collection to add to, must not be null |
---|---|
elements | the array of elements to add, must not be null |
NullPointerException | if the collection or array is null |
---|
Adds all elements in the enumeration to the given collection.
collection | the collection to add to, must not be null |
---|---|
enumeration | the enumeration of elements to add, must not be null |
NullPointerException | if the collection or enumeration is null |
---|
Adds an element to the collection unless the element is null.
collection | the collection to add to, must not be null |
---|---|
object | the object to add, if null it will not be added |
NullPointerException | if the collection is null |
---|
Returns the number of occurrences of obj in coll.
obj | the object to find the cardinality of |
---|---|
coll | the collection to search |
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.
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 |
NullPointerException | if the output collection is null |
---|
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.
inputCollection | the collection to get the input from, may not be null |
---|---|
transformer | the transformer to use, may be null |
NullPointerException | if the input collection is null |
---|
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.
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 |
NullPointerException | if the output collection is null |
---|
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.
inputIterator | the iterator to get the input from, may be null |
---|---|
transformer | the transformer to use, may be null |
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.
coll1 | the first collection, must not be null |
---|---|
coll2 | the first collection, must not be null |
true
iff the intersection of the collections is non-emptyCounts the number of elements in the input collection that match the predicate.
A null
collection or predicate matches no elements.
inputCollection | the collection to get the input from, may be null |
---|---|
predicate | the predicate to use, may be null |
Returns a Collection
containing the exclusive disjunction
(symmetric difference) of the given Collection
s.
The cardinality of each element e in the returned Collection
will be equal to
max(cardinality(e,a),cardinality(e,b)) - min(cardinality(e,a),cardinality(e,b)).
This is equivalent to
subtract
(union(a,b)
,intersection(a,b)
)
or
union
(subtract(a,b)
,subtract(b,a)
).
a | the first collection, must not be null |
---|---|
b | the second collection, must not be null |
Answers true if a predicate is true for at least one element of a collection.
A null
collection or predicate returns false.
collection | the collection to get the input from, may be null |
---|---|
predicate | the predicate to use, may be null |
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.
collection | the collection to get the input from, may be null |
---|---|
predicate | the predicate to use as a filter, may be null |
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.
collection | the collection to search, may be null |
---|---|
predicate | the predicate to use, may be null |
Executes the given closure on each element in the collection.
If the input collection or closure is null, there is no change made.
collection | the collection to get the input from, may be null |
---|---|
closure | the closure to perform, may be null |
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.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.object | the object to get a value from |
---|---|
index | the index to get |
IndexOutOfBoundsException | if the index is invalid |
---|---|
IllegalArgumentException | if the object type is invalid |
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.
coll | the collection to get the cardinality map for, must not be null |
---|
This method is deprecated.
use get(Object, int)
instead. Will be removed in v4.0
Given an Object, and an index, returns the nth value in the object.
obj | the object to get an index of, may be null |
---|---|
idx | the index to get |
IndexOutOfBoundsException | |
ArrayIndexOutOfBoundsException |
This method is deprecated.
use get(Object, int)
instead. Will be removed in v4.0
Given an Object, and a key (index), returns the value associated with that key in the Object. The following checks are made:
obj | the object to get an index of |
---|---|
index | the index to get |
IndexOutOfBoundsException | |
ArrayIndexOutOfBoundsException |
Returns a Collection
containing the intersection
of the given Collection
s.
The cardinality of each element in the returned Collection
will be equal to the minimum of the cardinality of that element
in the two given Collection
s.
a | the first collection, must not be null |
---|---|
b | the second collection, must not be null |
Null-safe check if the specified collection is empty.
Null returns true.
coll | the collection to check, may be null |
---|
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.
a | the first collection, must not be null |
---|---|
b | the second collection, must not be null |
true
iff the collections contain the same elements with the same cardinalities.
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.
coll | the collection to check |
---|
NullPointerException | if the collection is null |
---|
Null-safe check if the specified collection is not empty.
Null returns false.
coll | the collection to check, may be null |
---|
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
a | the first (sub?) collection, must not be null |
---|---|
b | the second (super?) collection, must not be null |
true
iff a is a proper sub-collection of bReturns 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.
a | the first (sub?) collection, must not be null |
---|---|
b | the second (super?) collection, must not be null |
true
iff a is a sub-collection of bGet 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.
coll | the collection to check |
---|
NullPointerException | if the collection is null |
---|
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.
collection | the collection to predicate, must not be null |
---|---|
predicate | the predicate for the collection, must not be null |
IllegalArgumentException | if the Collection is null |
---|
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);
.
collection | the collection from which items are removed (in the returned collection) |
---|---|
remove | the items to be removed from the returned collection |
Collection
containing all the elements of collection
except
any elements that also occur in remove
.NullPointerException | if either parameter is null |
---|
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);
.
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 |
Collection
containing all the elements of collection
that occur at least once in retain
.NullPointerException | if either parameter is null |
---|
Reverses the order of the given array.
array | the array to reverse |
---|
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.
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 |
Selects all elements from input collection which match the given predicate into an output collection.
A null
predicate matches no elements.
inputCollection | the collection to get the input from, may not be null |
---|---|
predicate | the predicate to use, may be null |
NullPointerException | if the input collection is null |
---|
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.
inputCollection | the collection to get the input from, may not be null |
---|---|
predicate | the predicate to use, may be null |
NullPointerException | if the input collection is null |
---|
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
.
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 |
Gets the size of the collection/iterator specified.
This method can handles objects as follows
object | the object to get the size of |
---|
IllegalArgumentException | thrown if object is not recognised or null |
---|
Checks if the specified collection/array/iterator is empty.
This method can handles objects as follows
Note: This method is named to avoid clashing with
isEmpty(Collection)
.
object | the object to get the size of, not null |
---|
IllegalArgumentException | thrown if object is not recognised or null |
---|
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.
a | the collection to subtract from, must not be null |
---|---|
b | the collection to subtract, must not be null |
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.
collection | the collection to synchronize, must not be null |
---|
IllegalArgumentException | if the collection is null |
---|
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.
collection | the collection to get the input from, may be null |
---|---|
transformer | the transformer to perform, may be null |
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.
collection | the collection to predicate, must not be null |
---|---|
transformer | the transformer for the collection, must not be null |
IllegalArgumentException | if the Collection or Transformer is null |
---|
Returns a typed collection backed by the given collection.
Only objects of the specified type can be added to the collection.
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 Collection
containing the union
of the given Collection
s.
The cardinality of each element in the returned Collection
will be equal to the maximum of the cardinality of that element
in the two given Collection
s.
a | the first collection, must not be null |
---|---|
b | the second collection, must not be null |
Returns an unmodifiable collection backed by the given collection.
This method uses the implementation in the decorators subpackage.
collection | the collection to make unmodifiable, must not be null |
---|
IllegalArgumentException | if the collection is null |
---|