public class CollectionUtils
extends java.lang.Object
Collection
instances.Modifier and Type | Field and Description |
---|---|
static java.util.Collection |
EMPTY_COLLECTION
An empty unmodifiable collection.
|
Constructor and Description |
---|
CollectionUtils()
CollectionUtils should not normally be instantiated. |
Modifier and Type | Method and Description |
---|---|
static void |
addAll(java.util.Collection collection,
java.util.Enumeration enumeration)
Adds all elements in the enumeration to the given collection.
|
static void |
addAll(java.util.Collection collection,
java.util.Iterator iterator)
Adds all elements in the iteration to the given collection.
|
static void |
addAll(java.util.Collection collection,
java.lang.Object[] elements)
Adds all elements in the array to the given collection.
|
static boolean |
addIgnoreNull(java.util.Collection collection,
java.lang.Object object)
Adds an element to the collection unless the element is null.
|
static int |
cardinality(java.lang.Object obj,
java.util.Collection coll)
Returns the number of occurrences of obj in coll.
|
static java.util.Collection |
collect(java.util.Collection inputCollection,
Transformer transformer)
Returns a new Collection consisting of the elements of inputCollection transformed
by the given transformer.
|
static java.util.Collection |
collect(java.util.Collection inputCollection,
Transformer transformer,
java.util.Collection outputCollection)
Transforms all elements from inputCollection with the given transformer
and adds them to the outputCollection.
|
static java.util.Collection |
collect(java.util.Iterator inputIterator,
Transformer transformer)
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
|
static java.util.Collection |
collect(java.util.Iterator inputIterator,
Transformer transformer,
java.util.Collection outputCollection)
Transforms all elements from the inputIterator with the given transformer
and adds them to the outputCollection.
|
static boolean |
containsAny(java.util.Collection coll1,
java.util.Collection coll2)
Returns
true iff at least one element is in both collections. |
static int |
countMatches(java.util.Collection inputCollection,
Predicate predicate)
Counts the number of elements in the input collection that match the predicate.
|
static java.util.Collection |
disjunction(java.util.Collection a,
java.util.Collection b)
Returns a
Collection containing the exclusive disjunction
(symmetric difference) of the given Collection s. |
static boolean |
exists(java.util.Collection collection,
Predicate predicate)
Answers true if a predicate is true for at least one element of a collection.
|
static void |
filter(java.util.Collection collection,
Predicate predicate)
Filter the collection by applying a Predicate to each element.
|
static java.lang.Object |
find(java.util.Collection collection,
Predicate predicate)
Finds the first element in the given collection which matches the given predicate.
|
static void |
forAllDo(java.util.Collection collection,
Closure closure)
Executes the given closure on each element in the collection.
|
static java.lang.Object |
get(java.lang.Object object,
int index)
Returns the
index -th value in object , throwing
IndexOutOfBoundsException if there is no such element or
IllegalArgumentException if object is not an
instance of one of the supported types. |
static java.util.Map |
getCardinalityMap(java.util.Collection coll)
Returns a
Map mapping each unique element in the given
Collection to an Integer representing the number
of occurrences of that element in the Collection . |
static java.lang.Object |
index(java.lang.Object obj,
int idx)
Deprecated.
use
get(Object, int) instead. Will be removed in v4.0 |
static java.lang.Object |
index(java.lang.Object obj,
java.lang.Object index)
Deprecated.
use
get(Object, int) instead. Will be removed in v4.0 |
static java.util.Collection |
intersection(java.util.Collection a,
java.util.Collection b)
Returns a
Collection containing the intersection
of the given Collection s. |
static boolean |
isEmpty(java.util.Collection coll)
Null-safe check if the specified collection is empty.
|
static boolean |
isEqualCollection(java.util.Collection a,
java.util.Collection b)
Returns true iff the given
Collection s contain
exactly the same elements with exactly the same cardinalities. |
static boolean |
isFull(java.util.Collection coll)
Returns true if no more elements can be added to the Collection.
|
static boolean |
isNotEmpty(java.util.Collection coll)
Null-safe check if the specified collection is not empty.
|
static boolean |
isProperSubCollection(java.util.Collection a,
java.util.Collection b)
Returns true iff a is a proper sub-collection of b,
that is, iff the cardinality of e in a is less
than or equal to the cardinality of e in b,
for each element e in a, and there is at least one
element f such that the cardinality of f in b
is strictly greater than the cardinality of f in a.
|
static boolean |
isSubCollection(java.util.Collection a,
java.util.Collection b)
Returns true iff a is a sub-collection of b,
that is, iff the cardinality of e in a is less
than or equal to the cardinality of e in b,
for each element e in a.
|
static int |
maxSize(java.util.Collection coll)
Get the maximum number of elements that the Collection can contain.
|
static java.util.Collection |
predicatedCollection(java.util.Collection collection,
Predicate predicate)
Returns a predicated (validating) collection backed by the given collection.
|
static java.util.Collection |
removeAll(java.util.Collection collection,
java.util.Collection remove)
Removes the elements in
remove from collection . |
static java.util.Collection |
retainAll(java.util.Collection collection,
java.util.Collection retain)
Returns a collection containing all the elements in
collection
that are also in retain . |
static void |
reverseArray(java.lang.Object[] array)
Reverses the order of the given array.
|
static java.util.Collection |
select(java.util.Collection inputCollection,
Predicate predicate)
Selects all elements from input collection which match the given predicate
into an output collection.
|
static void |
select(java.util.Collection inputCollection,
Predicate predicate,
java.util.Collection outputCollection)
Selects all elements from input collection which match the given predicate
and adds them to outputCollection.
|
static java.util.Collection |
selectRejected(java.util.Collection inputCollection,
Predicate predicate)
Selects all elements from inputCollection which don't match the given predicate
into an output collection.
|
static void |
selectRejected(java.util.Collection inputCollection,
Predicate predicate,
java.util.Collection outputCollection)
Selects all elements from inputCollection which don't match the given predicate
and adds them to outputCollection.
|
static int |
size(java.lang.Object object)
Gets the size of the collection/iterator specified.
|
static boolean |
sizeIsEmpty(java.lang.Object object)
Checks if the specified collection/array/iterator is empty.
|
static java.util.Collection |
subtract(java.util.Collection a,
java.util.Collection b)
Returns a new
Collection containing a - b. |
static java.util.Collection |
synchronizedCollection(java.util.Collection collection)
Returns a synchronized collection backed by the given collection.
|
static void |
transform(java.util.Collection collection,
Transformer transformer)
Transform the collection by applying a Transformer to each element.
|
static java.util.Collection |
transformedCollection(java.util.Collection collection,
Transformer transformer)
Returns a transformed bag backed by the given collection.
|
static java.util.Collection |
typedCollection(java.util.Collection collection,
java.lang.Class type)
Returns a typed collection backed by the given collection.
|
static java.util.Collection |
union(java.util.Collection a,
java.util.Collection b)
Returns a
Collection containing the union
of the given Collection s. |
static java.util.Collection |
unmodifiableCollection(java.util.Collection collection)
Returns an unmodifiable collection backed by the given collection.
|
public static final java.util.Collection EMPTY_COLLECTION
public CollectionUtils()
CollectionUtils
should not normally be instantiated.public static java.util.Collection union(java.util.Collection a, java.util.Collection b)
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 nullb
- the second collection, must not be nullCollection.addAll(java.util.Collection<? extends E>)
public static java.util.Collection intersection(java.util.Collection a, java.util.Collection b)
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 nullb
- the second collection, must not be nullCollection.retainAll(java.util.Collection<?>)
,
containsAny(java.util.Collection, java.util.Collection)
public static java.util.Collection disjunction(java.util.Collection a, java.util.Collection b)
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 nullb
- the second collection, must not be nullpublic static java.util.Collection subtract(java.util.Collection a, java.util.Collection b)
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 nullb
- the collection to subtract, must not be nullCollection.removeAll(java.util.Collection<?>)
public static boolean containsAny(java.util.Collection coll1, java.util.Collection coll2)
true
iff at least one element is in both collections.
In other words, this method returns true
iff the
intersection(java.util.Collection, java.util.Collection)
of coll1 and coll2 is not empty.
coll1
- the first collection, must not be nullcoll2
- the first collection, must not be nulltrue
iff the intersection of the collections is non-emptyintersection(java.util.Collection, java.util.Collection)
public static java.util.Map getCardinalityMap(java.util.Collection coll)
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 nullpublic static boolean isSubCollection(java.util.Collection a, java.util.Collection b)
a
- the first (sub?) collection, must not be nullb
- the second (super?) collection, must not be nulltrue
iff a is a sub-collection of bisProperSubCollection(java.util.Collection, java.util.Collection)
,
Collection.containsAll(java.util.Collection<?>)
public static boolean isProperSubCollection(java.util.Collection a, java.util.Collection b)
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 nullb
- the second (super?) collection, must not be nulltrue
iff a is a proper sub-collection of bisSubCollection(java.util.Collection, java.util.Collection)
,
Collection.containsAll(java.util.Collection<?>)
public static boolean isEqualCollection(java.util.Collection a, java.util.Collection b)
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 nullb
- the second collection, must not be nulltrue
iff the collections contain the same elements with the same cardinalities.public static int cardinality(java.lang.Object obj, java.util.Collection coll)
obj
- the object to find the cardinality ofcoll
- the collection to searchpublic static java.lang.Object find(java.util.Collection collection, Predicate 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 nullpredicate
- the predicate to use, may be nullpublic static void forAllDo(java.util.Collection collection, Closure closure)
If the input collection or closure is null, there is no change made.
collection
- the collection to get the input from, may be nullclosure
- the closure to perform, may be nullpublic static void filter(java.util.Collection collection, Predicate predicate)
If the input collection or predicate is null, there is no change made.
collection
- the collection to get the input from, may be nullpredicate
- the predicate to use as a filter, may be nullpublic static void transform(java.util.Collection collection, Transformer transformer)
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 nulltransformer
- the transformer to perform, may be nullpublic static int countMatches(java.util.Collection inputCollection, Predicate predicate)
A null
collection or predicate matches no elements.
inputCollection
- the collection to get the input from, may be nullpredicate
- the predicate to use, may be nullpublic static boolean exists(java.util.Collection collection, Predicate predicate)
A null
collection or predicate returns false.
collection
- the collection to get the input from, may be nullpredicate
- the predicate to use, may be nullpublic static java.util.Collection select(java.util.Collection inputCollection, Predicate predicate)
A null
predicate matches no elements.
inputCollection
- the collection to get the input from, may not be nullpredicate
- the predicate to use, may be nulljava.lang.NullPointerException
- if the input collection is nullpublic static void select(java.util.Collection inputCollection, Predicate predicate, java.util.Collection 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 nullpredicate
- the predicate to use, may be nulloutputCollection
- the collection to output into, may not be nullpublic static java.util.Collection selectRejected(java.util.Collection inputCollection, Predicate predicate)
If the input predicate is null
, the result is an empty list.
inputCollection
- the collection to get the input from, may not be nullpredicate
- the predicate to use, may be nulljava.lang.NullPointerException
- if the input collection is nullpublic static void selectRejected(java.util.Collection inputCollection, Predicate predicate, java.util.Collection outputCollection)
If the input predicate is null
, no elements are added to outputCollection
.
inputCollection
- the collection to get the input from, may be nullpredicate
- the predicate to use, may be nulloutputCollection
- the collection to output into, may not be nullpublic static java.util.Collection collect(java.util.Collection inputCollection, Transformer transformer)
If the input transformer is null, the result is an empty list.
inputCollection
- the collection to get the input from, may not be nulltransformer
- the transformer to use, may be nulljava.lang.NullPointerException
- if the input collection is nullpublic static java.util.Collection collect(java.util.Iterator inputIterator, Transformer transformer)
If the input iterator or transformer is null, the result is an empty list.
inputIterator
- the iterator to get the input from, may be nulltransformer
- the transformer to use, may be nullpublic static java.util.Collection collect(java.util.Collection inputCollection, Transformer transformer, java.util.Collection 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 nulltransformer
- the transformer to use, may be nulloutputCollection
- the collection to output into, may not be nulljava.lang.NullPointerException
- if the output collection is nullpublic static java.util.Collection collect(java.util.Iterator inputIterator, Transformer transformer, java.util.Collection 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 nulltransformer
- the transformer to use, may be nulloutputCollection
- the collection to output into, may not be nulljava.lang.NullPointerException
- if the output collection is nullpublic static boolean addIgnoreNull(java.util.Collection collection, java.lang.Object object)
collection
- the collection to add to, must not be nullobject
- the object to add, if null it will not be addedjava.lang.NullPointerException
- if the collection is nullpublic static void addAll(java.util.Collection collection, java.util.Iterator iterator)
collection
- the collection to add to, must not be nulliterator
- the iterator of elements to add, must not be nulljava.lang.NullPointerException
- if the collection or iterator is nullpublic static void addAll(java.util.Collection collection, java.util.Enumeration enumeration)
collection
- the collection to add to, must not be nullenumeration
- the enumeration of elements to add, must not be nulljava.lang.NullPointerException
- if the collection or enumeration is nullpublic static void addAll(java.util.Collection collection, java.lang.Object[] elements)
collection
- the collection to add to, must not be nullelements
- the array of elements to add, must not be nulljava.lang.NullPointerException
- if the collection or array is nullpublic static java.lang.Object index(java.lang.Object obj, int idx)
get(Object, int)
instead. Will be removed in v4.0obj
- the object to get an index of, may be nullidx
- the index to getjava.lang.IndexOutOfBoundsException
java.lang.ArrayIndexOutOfBoundsException
public static java.lang.Object index(java.lang.Object obj, java.lang.Object index)
get(Object, int)
instead. Will be removed in v4.0obj
- the object to get an index ofindex
- the index to getjava.lang.IndexOutOfBoundsException
java.lang.ArrayIndexOutOfBoundsException
public static java.lang.Object get(java.lang.Object object, int index)
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 fromindex
- the index to getjava.lang.IndexOutOfBoundsException
- if the index is invalidjava.lang.IllegalArgumentException
- if the object type is invalidpublic static int size(java.lang.Object object)
This method can handles objects as follows
object
- the object to get the size ofjava.lang.IllegalArgumentException
- thrown if object is not recognised or nullpublic static boolean sizeIsEmpty(java.lang.Object object)
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 nulljava.lang.IllegalArgumentException
- thrown if object is not recognised or nullpublic static boolean isEmpty(java.util.Collection coll)
Null returns true.
coll
- the collection to check, may be nullpublic static boolean isNotEmpty(java.util.Collection coll)
Null returns false.
coll
- the collection to check, may be nullpublic static void reverseArray(java.lang.Object[] array)
array
- the array to reversepublic static boolean isFull(java.util.Collection coll)
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 checkjava.lang.NullPointerException
- if the collection is nullpublic static int maxSize(java.util.Collection coll)
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 checkjava.lang.NullPointerException
- if the collection is nullpublic static java.util.Collection retainAll(java.util.Collection collection, java.util.Collection retain)
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 operationretain
- the collection containing the elements to be retained in the returned collectionCollection
containing all the elements of collection
that occur at least once in retain
.java.lang.NullPointerException
- if either parameter is nullpublic static java.util.Collection removeAll(java.util.Collection collection, java.util.Collection remove)
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
.java.lang.NullPointerException
- if either parameter is nullpublic static java.util.Collection synchronizedCollection(java.util.Collection 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 nulljava.lang.IllegalArgumentException
- if the collection is nullpublic static java.util.Collection unmodifiableCollection(java.util.Collection collection)
This method uses the implementation in the decorators subpackage.
collection
- the collection to make unmodifiable, must not be nulljava.lang.IllegalArgumentException
- if the collection is nullpublic static java.util.Collection predicatedCollection(java.util.Collection collection, Predicate predicate)
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 nullpredicate
- the predicate for the collection, must not be nulljava.lang.IllegalArgumentException
- if the Collection is nullpublic static java.util.Collection typedCollection(java.util.Collection collection, java.lang.Class type)
Only objects of the specified type can be added to the collection.
collection
- the collection to limit to a specific type, must not be nulltype
- the type of objects which may be added to the collectionpublic static java.util.Collection transformedCollection(java.util.Collection collection, Transformer transformer)
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 nulltransformer
- the transformer for the collection, must not be nulljava.lang.IllegalArgumentException
- if the Collection or Transformer is nullCopyright © 2010 - 2020 Adobe. All Rights Reserved