Prev Class | Next Class | Frames | No Frames |
Summary: Nested | Field | Method | Constr | Detail: Nested | Field | Method | Constr |
java.lang.Object
org.apache.commons.collections.CollectionUtils
public class CollectionUtils
extends java.lang.Object
Collection
instances.
Field Summary | |
static Collection |
|
Constructor Summary | |
|
Method Summary | |
static void |
|
static void |
|
static void |
|
static int |
|
static Collection |
|
static Collection |
|
static Collection |
|
static Collection |
|
static boolean |
|
static int |
|
static Collection |
|
static boolean | |
static void | |
static Object | |
static void | |
static Object |
|
static Map |
|
static Object |
|
static Object |
|
static Collection |
|
static boolean |
|
static boolean |
|
static boolean |
|
static boolean |
|
static int |
|
static Collection |
|
static void |
|
static Collection | |
static void | |
static Collection |
|
static void |
|
static int |
|
static Collection |
|
static Collection |
|
static void |
|
static Collection |
|
static Collection |
|
static Collection |
|
static 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.
public static void addAll(Collection collection, Enumeration enumeration)
Adds all elements in the enumeration to the given collection.
- Parameters:
collection
- the collection to add toenumeration
- the enumeration of elements to add, may not be null
public static void addAll(Collection collection, Iterator iterator)
Adds all elements in the iteration to the given collection.
- Parameters:
collection
- the collection to add toiterator
- the iterator of elements to add, may not be null
public static void addAll(Collection collection, Object[] elements)
Adds all elements in the array to the given collection.
- Parameters:
collection
- the collection to add to, may not be nullelements
- the array of elements to add, may not be null
public static int cardinality(Object obj, Collection coll)
Returns the number of occurrences of obj in coll.
- Parameters:
obj
- the object to find the cardinality ofcoll
- the collection to search
- Returns:
- the the number of occurrences of obj in coll
public static Collection collect(Collection inputCollection, Transformer 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.
- Parameters:
inputCollection
- the collection to get the input from, may not be nulltransformer
- the transformer to use, may be null
- Returns:
- the transformed result (new list)
public static Collection collect(Collection inputCollection, Transformer transformer, Collection 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.
- Parameters:
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 null
- Returns:
- the outputCollection with the transformed input added
public static Collection collect(Iterator inputIterator, Transformer 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.
- Parameters:
inputIterator
- the iterator to get the input from, may be nulltransformer
- the transformer to use, may be null
- Returns:
- the transformed result (new list)
public 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. 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 nulltransformer
- the transformer to use, may be nulloutputCollection
- the collection to output into, may not be null
- Returns:
- the outputCollection with the transformed input added
public static boolean containsAny(Collection coll1, Collection coll2)
Returnstrue
iff at least one element is in both collections. In other words, this method returnstrue
iff theintersection(Collection,Collection)
of coll1 and coll2 is not empty.
- Parameters:
coll1
- the first collection, must not be nullcoll2
- the first collection, must not be null
- Returns:
true
iff the intersection of the collections is non-empty
- Since:
- 2.1
- See Also:
intersection(Collection,Collection)
public static int countMatches(Collection inputCollection, Predicate predicate)
Counts the number of elements in the input collection that match the predicate. Anull
collection or predicate matches no elements.
- Parameters:
inputCollection
- the collection to get the input from, may be nullpredicate
- the predicate to use, may be null
- Returns:
- the number of matches for the predicate in the collection
public static Collection disjunction(Collection a, Collection b)
Returns aCollection
containing the exclusive disjunction (symmetric difference) of the givenCollection
s. The cardinality of each element e in the returnedCollection
will be equal to max(cardinality(e,a),cardinality(e,b)) - min(cardinality(e,a),cardinality(e,b)). This is equivalent tosubtract
(union(a,b)
,intersection(a,b)
) orunion
(subtract(a,b)
,subtract(b,a)
).
- Parameters:
a
- the first collection, must not be nullb
- the second collection, must not be null
- Returns:
- the symmetric difference of the two collections
public static boolean exists(Collection collection, Predicate predicate)
Answers true if a predicate is true for at least one element of a collection. Anull
collection or predicate returns false.
- Parameters:
collection
- the collection to get the input from, may be nullpredicate
- the predicate to use, may be null
- Returns:
- true if at least one element of the collection matches the predicate
public static void filter(Collection collection, Predicate 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.
- Parameters:
collection
- the collection to get the input from, may be nullpredicate
- the predicate to use as a filter, may be null
public static Object find(Collection collection, Predicate 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.
- Parameters:
collection
- the collection to search, may be nullpredicate
- 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
public static void forAllDo(Collection collection, Closure closure)
Executes the given closure on each element in the collection. If the input collection or closure is null, there is no change made.
- Parameters:
collection
- the collection to get the input from, may be nullclosure
- the closure to perform, may be null
public static Object get(Object object, int index)
Returns theindex
-th value inobject
, throwingIndexOutOfBoundsException
if there is no such element orIllegalArgumentException
ifobject
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 positionindex
in the map'sentrySet
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 anIndexOutOfBoundsException
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 toindex
(or to the end, ifindex
exceeds the number of entries) as a side effect of this method.
- Parameters:
object
- the object to get a value fromindex
- the index to get
- Returns:
- the object at the specified index
public static Map getCardinalityMap(Collection coll)
Returns aMap
mapping each unique element in the givenCollection
to anInteger
representing the number of occurrences of that element in theCollection
. 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
public static Object index(Object obj, Object index)
Deprecated. use
get(Object,int)
instead. Will be removed in v4.0Given 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.
- Parameters:
obj
- the object to get an index ofindex
- the index to get
- Returns:
- the object at the specified index
public static Object index(Object obj, int idx)
Deprecated. use
get(Object,int)
instead. Will be removed in v4.0Given 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.
- Parameters:
obj
- the object to get an index of, may be nullidx
- the index to get
public static Collection intersection(Collection a, Collection b)
Returns aCollection
containing the intersection of the givenCollection
s. The cardinality of each element in the returnedCollection
will be equal to the minimum of the cardinality of that element in the two givenCollection
s.
- Parameters:
a
- the first collection, must not be nullb
- the second collection, must not be null
- Returns:
- the intersection of the two collections
- See Also:
Collection.retainAll
,containsAny(Collection,Collection)
public static boolean isEqualCollection(Collection a, Collection b)
Returns true iff the givenCollection
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 nullb
- the second collection, must not be null
- Returns:
true
iff the collections contain the same elements with the same cardinalities.
public static boolean isFull(Collection coll)
Returns true if no more elements can be added to the Collection. This method uses theBoundedCollection
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
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()
andb.size()
represent the total cardinality of a and b, resp.a.size() <32Integer.MAXVALUE
- Parameters:
a
- the first (sub?) collection, must not be nullb
- the second (super?) collection, must not be null
- Returns:
true
iff a is a proper sub-collection of b
- See Also:
isSubCollection(Collection,Collection)
,Collection.containsAll
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 nullb
- the second (super?) collection, must not be null
- Returns:
true
iff a is a sub-collection of b
- See Also:
isProperSubCollection(Collection,Collection)
,Collection.containsAll
public static int maxSize(Collection coll)
Get the maximum number of elements that the Collection can contain. This method uses theBoundedCollection
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
public static Collection predicatedCollection(Collection collection, Predicate 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.
- Parameters:
collection
- the collection to predicate, must not be nullpredicate
- the predicate for the collection, must not be null
- Returns:
- a predicated collection backed by the given collection
public static void reverseArray(Object[] array)
Reverses the order of the given array.
- Parameters:
array
- the array to reverse
public static Collection select(Collection inputCollection, Predicate predicate)
Selects all elements from input collection which match the given predicate into an output collection. Anull
predicate matches no elements.
- Parameters:
inputCollection
- the collection to get the input from, may not be nullpredicate
- the predicate to use, may be null
- Returns:
- the elements matching the predicate (new list)
public 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. 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 nullpredicate
- the predicate to use, may be nulloutputCollection
- the collection to output into, may not be null
public static Collection selectRejected(Collection inputCollection, Predicate predicate)
Selects all elements from inputCollection which don't match the given predicate into an output collection. If the input predicate isnull
, the result is an empty list.
- Parameters:
inputCollection
- the collection to get the input from, may not be nullpredicate
- the predicate to use, may be null
- Returns:
- the elements not matching the predicate (new list)
public 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. If the input predicate isnull
, no elements are added tooutputCollection
.
- Parameters:
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 null
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
- Returns:
- the size of the specified collection
- Since:
- Commons Collections 3.1
public static Collection subtract(Collection a, Collection b)
Returns a newCollection
containing a - b. The cardinality of each element e in the returnedCollection
will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.
- Parameters:
a
- the collection to subtract from, must not be nullb
- the collection to subtract, must not be null
- Returns:
- a new collection with the results
- See Also:
Collection.removeAll
public static Collection synchronizedCollection(Collection 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.
- Parameters:
collection
- the collection to synchronize, must not be null
- Returns:
- a synchronized collection backed by the given collection
public static void transform(Collection collection, Transformer 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.
- Parameters:
collection
- the collection to get the input from, may be nulltransformer
- the transformer to perform, may be null
public static Collection transformedCollection(Collection collection, Transformer 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.
- Parameters:
collection
- the collection to predicate, must not be nulltransformer
- the transformer for the collection, must not be null
- Returns:
- a transformed collection backed by the given collection
public static Collection typedCollection(Collection collection, Class type)
Returns a typed collection backed by the given collection. 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 nulltype
- the type of objects which may be added to the collection
- Returns:
- a typed collection backed by the specified collection
public static Collection union(Collection a, Collection b)
Returns aCollection
containing the union of the givenCollection
s. The cardinality of each element in the returnedCollection
will be equal to the maximum of the cardinality of that element in the two givenCollection
s.
- Parameters:
a
- the first collection, must not be nullb
- the second collection, must not be null
- Returns:
- the union of the two collections
- See Also:
Collection.addAll
public static Collection unmodifiableCollection(Collection collection)
Returns an unmodifiable collection backed by the given collection. 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