public class CollectionUtils extends Object
Collection instances.
Various utility methods might put the input objects into a Set/Map/Bag. In case the input objects override Object, it is mandatory that the general contract of the Object method is maintained.
NOTE: From 4.0, method parameters will take Iterable objects when possible.
| Modifier and Type | Field and Description |
|---|---|
static Collection |
EMPTY_COLLECTION
An empty unmodifiable collection.
|
| Modifier and Type | Method and Description |
|---|---|
static <C> boolean |
addAll(Collection
Adds all elements in the array to the given collection.
|
static <C> boolean |
addAll(Collection
Adds all elements in the enumeration to the given collection.
|
static <C> boolean |
addAll(Collection
Adds all elements in the
Iterable to the given collection.
|
static <C> boolean |
addAll(Collection
Adds all elements in the iteration to the given collection.
|
static <T> boolean |
addIgnoreNull(Collection
Adds an element to the collection unless the element is null.
|
static <O> int |
cardinality(O obj, Iterable
Deprecated.
since 4.1, use
IterableUtils instead. Be aware that the order of parameters has changed.
|
static <O extends Comparable |
collate(Iterable
Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
|
static <O extends Comparable |
collate(Iterable
Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
|
static <O> List |
collate(Iterable
Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.
|
static <O> List |
collate(Iterable
Merges two sorted Collections, a and b, into a single, sorted List such that the ordering of the elements according to Comparator c is retained.
|
static <I |
collect(Iterable
Transforms all elements from input collection with the given transformer and adds them to the output collection.
|
static <I |
collect(Iterable
Returns a new Collection containing all elements of the input collection transformed by the given transformer.
|
static <I |
collect(Iterator
Transforms all elements from the input iterator with the given transformer and adds them to the output collection.
|
static <I |
collect(Iterator
Transforms all elements from the input iterator with the given transformer and adds them to the output collection.
|
static boolean |
containsAll(Collection
Returns
true iff all elements of
coll2 are also contained in
coll1.
|
static boolean |
containsAny(Collection
Returns
true iff at least one element is in both collections.
|
static <C> int |
countMatches(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static <O> Collection |
disjunction(Iterable
Returns a
Collection containing the exclusive disjunction (symmetric difference) of the given
Iterables.
|
static <T> Collection |
emptyCollection()
Returns the immutable EMPTY_COLLECTION with generic type safety.
|
static <T> Collection |
emptyIfNull(Collection
Returns an immutable empty collection if the argument is
null, or the argument itself otherwise.
|
static <C> boolean |
exists(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static <E> E |
extractSingleton(Collection
Extract the lone element of the specified Collection.
|
static <T> boolean |
filter(Iterable
Filter the collection by applying a Predicate to each element.
|
static <T> boolean |
filterInverse(Iterable
Filter the collection by applying a Predicate to each element.
|
static <T> T |
find(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static <T |
forAllButLastDo(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static <T |
forAllButLastDo(Iterator
Deprecated.
since 4.1, use
IteratorUtils instead
|
static <T |
forAllDo(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static <T |
forAllDo(Iterator
Deprecated.
since 4.1, use
IteratorUtils instead
|
static <T> T |
get(Iterable
Deprecated.
since 4.1, use
IterableUtils.get(Iterable, int) instead
|
static <T> T |
get(Iterator
Deprecated.
since 4.1, use
IteratorUtils.get(Iterator, int) instead
|
static <K |
get(Map
Returns the
index-th
Map.Entry in the
map's
entrySet, throwing
IndexOutOfBoundsException if there is no such element.
|
static Object |
get(Object
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 <O> Map |
getCardinalityMap(Iterable
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 <O> Collection |
intersection(Iterable
Returns a
Collection containing the intersection of the given
Iterables.
|
static boolean |
isEmpty(Collection
Null-safe check if the specified collection is empty.
|
static boolean |
isEqualCollection(Collection
Returns
true iff the given
Collections contain exactly the same elements with exactly the same cardinalities.
|
static <E> boolean |
isEqualCollection(Collection
Returns
true iff the given
Collections contain exactly the same elements with exactly the same cardinalities.
|
static boolean |
isFull(Collection
Returns true if no more elements can be added to the Collection.
|
static boolean |
isNotEmpty(Collection
Null-safe check if the specified collection is not empty.
|
static boolean |
isProperSubCollection(Collection
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
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 <C> boolean |
matchesAll(Iterable
Deprecated.
since 4.1, use
IterableUtils instead
|
static int |
maxSize(Collection
Get the maximum number of elements that the Collection can contain.
|
static <E> Collection |
permutations(Collection
Returns a
Collection of all the permutations of the input collection.
|
static <C> Collection |
predicatedCollection(Collection
Returns a predicated (validating) collection backed by the given collection.
|
static <E> Collection |
removeAll(Collection
Removes the elements in
remove from
collection.
|
static <E> Collection |
removeAll(Iterable
Removes all elements in
remove from
collection.
|
static <C> Collection |
retainAll(Collection
Returns a collection containing all the elements in
collection that are also in
retain.
|
static <E> Collection |
retainAll(Iterable
Returns a collection containing all the elements in
collection that are also in
retain.
|
static void |
reverseArray(Object
Reverses the order of the given array.
|
static <O> Collection |
select(Iterable
Selects all elements from input collection which match the given predicate into an output collection.
|
static <O |
select(Iterable
Selects all elements from input collection which match the given predicate and adds them to outputCollection.
|
static <O |
select(Iterable
Selects all elements from inputCollection into an output and rejected collection, based on the evaluation of the given predicate.
|
static <O> Collection |
selectRejected(Iterable
Selects all elements from inputCollection which don't match the given predicate into an output collection.
|
static <O |
selectRejected(Iterable
Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.
|
static int |
size(Object
Gets the size of the collection/iterator specified.
|
static boolean |
sizeIsEmpty(Object
Checks if the specified collection/array/iterator is empty.
|
static <O> Collection |
subtract(Iterable
Returns a new
Collection containing
<i>a</i> - <i>b</i>.
|
static <O> Collection |
subtract(Iterable
Returns a new
Collection containing
a minus a subset of
b.
|
static <C> Collection |
synchronizedCollection(Collection
Deprecated.
since 4.1, use
Collections instead
|
static <C> void |
transform(Collection
Transform the collection by applying a Transformer to each element.
|
static <E> Collection |
transformingCollection(Collection
Returns a transformed bag backed by the given collection.
|
static <O> Collection |
union(Iterable
Returns a
Collection containing the union of the given
Iterables.
|
static <C> Collection |
unmodifiableCollection(Collection
Deprecated.
since 4.1, use
Collections instead
|
public static final CollectionEMPTY_COLLECTION
public static <T> Collection<T> emptyCollection()
T - the element type
EMPTY_COLLECTION
public static <T> Collection<T> emptyIfNull(Collection <T> collection)
null, or the argument itself otherwise.
T - the element type
collection - the collection, possibly
null
null
public static <O> Collection<O> union(Iterable <? extends O> a, Iterable <? extends O> b)
Collection containing the union of the given
Iterables.
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 Iterables.
O - the generic type that is able to represent the types contained in both input collections.
a - the first collection, must not be null
b - the second collection, must not be null
Collection.addAll(java.util.Collection<? extends E>)
public static <O> Collection<O> intersection(Iterable <? extends O> a, Iterable <? extends O> b)
Collection containing the intersection of the given
Iterables.
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 Iterables.
O - the generic type that is able to represent the types contained in both input collections.
a - the first collection, must not be null
b - the second collection, must not be null
Collection.retainAll(java.util.Collection<?>) ,
containsAny(java.util.Collection<?>, java.util.Collection<?>)
public static <O> Collection<O> disjunction(Iterable <? extends O> a, Iterable <? extends O> b)
Collection containing the exclusive disjunction (symmetric difference) of the given
Iterables.
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 {@link #subtract subtract}({@link #union union(a,b)},{@link #intersection intersection(a,b)}) or {@link #union union}({@link #subtract subtract(a,b)},{@link #subtract subtract(b,a)}).
O - the generic type that is able to represent the types contained in both input collections.
a - the first collection, must not be null
b - the second collection, must not be null
public static <O> Collection<O> subtract(Iterable <? extends O> a, Iterable <? extends O> b)
Collection containing
<i>a</i> - <i>b</i>. 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.
O - the generic type that is able to represent the types contained in both input collections.
a - the collection to subtract from, must not be null
b - the collection to subtract, must not be null
Collection.removeAll(java.util.Collection<?>)
public static <O> Collection<O> subtract(Iterable <? extends O> a, Iterable <? extends O> b, Predicate <O> p)
Collection containing
a minus a subset of
b. Only the elements of
b that satisfy the predicate condition,
p are subtracted from
a.
The cardinality of each element e in the returned Collection that satisfies the predicate condition will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.
The cardinality of each element e in the returned Collection that does not satisfy the predicate condition will be equal to the cardinality of e in a.
O - the generic type that is able to represent the types contained in both input collections.
a - the collection to subtract from, must not be null
b - the collection to subtract, must not be null
p - the condition used to determine which elements of
b are subtracted.
Collection.removeAll(java.util.Collection<?>)
public static boolean containsAll(Collection<?> coll1, Collection <?> coll2)
true iff all elements of
coll2 are also contained in
coll1. The cardinality of values in
coll2 is not taken into account, which is the same behavior as
Collection.containsAll(Collection) .
In other words, this method returns true iff the intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>) of coll1 and coll2 has the same cardinality as the set of unique values from coll2. In case coll2 is empty, true will be returned.
This method is intended as a replacement for Collection with a guaranteed runtime complexity of O(n + m). Depending on the type of Collection provided, this method will be much faster than calling Collection instead, though this will come at the cost of an additional space complexity O(n).
coll1 - the first collection, must not be null
coll2 - the second collection, must not be null
true iff the intersection of the collections has the same cardinality as the set of unique elements from the second collection
public static boolean containsAny(Collection<?> coll1, Collection <?> coll2)
true iff at least one element is in both collections.
In other words, this method returns true iff the intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>) of coll1 and coll2 is not empty.
coll1 - the first collection, must not be null
coll2 - the second collection, must not be null
true iff the intersection of the collections is non-empty
intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)
public static <O> Map<O ,Integer > getCardinalityMap(Iterable <? extends O> 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.
O - the type of object in the returned
Map. This is a super type of
.
coll - the collection to get the cardinality map for, must not be null
public static boolean isSubCollection(Collection<?> a, Collection <?> b)
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
b
isProperSubCollection(java.util.Collection<?>, java.util.Collection<?>),
Collection.containsAll(java.util.Collection<?>)
public static boolean isProperSubCollection(Collection<?> a, Collection <?> b)
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.MAXVALUEa - 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
b
isSubCollection(java.util.Collection<?>, java.util.Collection<?>),
Collection.containsAll(java.util.Collection<?>)
public static boolean isEqualCollection(Collection<?> a, Collection <?> b)
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.
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.
public static <E> boolean isEqualCollection(Collection<? extends E> a, Collection <? extends E> b, Equator <? super E> equator)
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.
Note: from version 4.1 onwards this method requires the input collections and equator to be of compatible type (using bounded wildcards). Providing incompatible arguments (e.g. by casting to their rawtypes) will result in a ClassCastException thrown at runtime.
E - the element type
a - the first collection, must not be null
b - the second collection, must not be null
equator - the Equator used for testing equality
true iff the collections contain the same elements with the same cardinalities.
NullPointerException - if the equator is null
@Deprecated public static <O> int cardinality(O obj, Iterable<? super O> coll)
IterableUtils.frequency(Iterable, Object) instead. Be aware that the order of parameters has changed.
O - the type of object that the
Iterable may contain.
obj - the object to find the cardinality of
coll - the
Iterable to search
NullPointerException - if coll is null
@Deprecated public static <T> T find(Iterable<T> collection, Predicate <? super T> predicate)
IterableUtils.find(Iterable, Predicate) instead
If the input collection or predicate is null, or no element of the collection matches the predicate, null is returned.
T - the type of object the
Iterable contains
collection - the collection to search, may be null
predicate - the predicate to use, may be null
@Deprecated public static <T,C extends Closure <? super T>> C forAllDo(Iterable <T> collection, C closure)
IterableUtils.forEach(Iterable, Closure) instead
If the input collection or closure is null, there is no change made.
T - the type of object the
Iterable contains
C - the closure type
collection - the collection to get the input from, may be null
closure - the closure to perform, may be null
@Deprecated public static <T,C extends Closure <? super T>> C forAllDo(Iterator <T> iterator, C closure)
IteratorUtils.forEach(Iterator, Closure) instead
If the input collection or closure is null, there is no change made.
T - the type of object the
Iterator contains
C - the closure type
iterator - the iterator to get the input from, may be null
closure - the closure to perform, may be null
@Deprecated public static <T,C extends Closure <? super T>> T forAllButLastDo(Iterable <T> collection, C closure)
IterableUtils.forEachButLast(Iterable, Closure) instead
If the input collection or closure is null, there is no change made.
T - the type of object the
Iterable contains
C - the closure type
collection - the collection to get the input from, may be null
closure - the closure to perform, may be null
@Deprecated public static <T,C extends Closure <? super T>> T forAllButLastDo(Iterator <T> iterator, C closure)
IteratorUtils.forEachButLast(Iterator, Closure) instead
If the input collection or closure is null, there is no change made.
T - the type of object the
Collection contains
C - the closure type
iterator - the iterator to get the input from, may be null
closure - the closure to perform, may be null
public static <T> boolean filter(Iterable<T> collection, Predicate <? super T> predicate)
If the input collection or predicate is null, there is no change made.
T - the type of object the
Iterable contains
collection - the collection to get the input from, may be null
predicate - the predicate to use as a filter, may be null
public static <T> boolean filterInverse(Iterable<T> collection, Predicate <? super T> predicate)
This is equivalent to
filter(collection, PredicateUtils.notPredicate(predicate))if predicate is != null.
If the input collection or predicate is null, there is no change made.
T - the type of object the
Iterable contains
collection - the collection to get the input from, may be null
predicate - the predicate to use as a filter, may be null
public static <C> void transform(Collection<C> collection, Transformer <? super C ,? extends C> 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.
C - the type of object the
Collection contains
collection - the
Collection to get the input from, may be null
transformer - the transformer to perform, may be null
@Deprecated public static <C> int countMatches(Iterable<C> input, Predicate <? super C> predicate)
IterableUtils.countMatches(Iterable, Predicate) instead
A null collection or predicate matches no elements.
@Deprecated public static <C> boolean exists(Iterable<C> input, Predicate <? super C> predicate)
IterableUtils.matchesAny(Iterable, Predicate) instead
A null collection or predicate returns false.
@Deprecated public static <C> boolean matchesAll(Iterable<C> input, Predicate <? super C> predicate)
IterableUtils.matchesAll(Iterable, Predicate) instead
A null predicate returns false.
A null or empty collection returns true.
C - the type of object the
Iterable contains
input - the
Iterable to get the input from, may be null
predicate - the predicate to use, may be null
public static <O> Collection<O> select(Iterable <? extends O> inputCollection, Predicate <? super O> predicate)
A null predicate matches no elements.
O - the type of object the
Iterable contains
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
public static <O,R extends Collection <? super O>> R select(Iterable <? extends O> inputCollection, Predicate <? super O> predicate, R outputCollection)
If the input collection or predicate is null, there is no change to the output collection.
O - the type of object the
Iterable contains
R - the type of 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 if the inputCollection and predicate or not null
public static <O,R extends Collection <? super O>> R select(Iterable <? extends O> inputCollection, Predicate <? super O> predicate, R outputCollection, R rejectedCollection)
Elements matching the predicate are added to the outputCollection, all other elements are added to the rejectedCollection.
If the input predicate is null, no elements are added to outputCollection or rejectedCollection.
Note: calling the method is equivalent to the following code snippet:
select(inputCollection, predicate, outputCollection); selectRejected(inputCollection, predicate, rejectedCollection);
O - the type of object the
Iterable contains
R - the type of 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 selected elements into, may not be null if the inputCollection and predicate are not null
rejectedCollection - the collection to output rejected elements into, may not be null if the inputCollection or predicate are not null
public static <O> Collection<O> selectRejected(Iterable <? extends O> inputCollection, Predicate <? super O> predicate)
If the input predicate is null, the result is an empty list.
O - the type of object the
Iterable contains
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
public static <O,R extends Collection <? super O>> R selectRejected(Iterable <? extends O> inputCollection, Predicate <? super O> predicate, R outputCollection)
If the input predicate is null, no elements are added to outputCollection.
O - the type of object the
Iterable contains
R - the type of 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 if the inputCollection and predicate or not null
public static <I,O> Collection <O> collect(Iterable <I> inputCollection, Transformer <? super I ,? extends O> transformer)
If the input collection or transformer is null, the result is an empty list.
I - the type of object in the input collection
O - the type of object in the output collection
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
public static <I,O> Collection <O> collect(Iterator <I> inputIterator, Transformer <? super I ,? extends O> transformer)
If the input iterator or transformer is null, the result is an empty list.
I - the type of object in the input collection
O - the type of object in the output collection
inputIterator - the iterator to get the input from, may be null
transformer - the transformer to use, may be null
public static <I,O ,R extends Collection <? super O>> R collect(Iterable <? extends I> inputCollection, Transformer <? super I ,? extends O> transformer, R outputCollection)
If the input collection or transformer is null, there is no change to the output collection.
I - the type of object in the input collection
O - the type of object in the output collection
R - the type of 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 if inputCollection and transformer are not null
NullPointerException - if the outputCollection is null and both, inputCollection and transformer are not null
public static <I,O ,R extends Collection <? super O>> R collect(Iterator <? extends I> inputIterator, Transformer <? super I ,? extends O> transformer, R outputCollection)
If the input iterator or transformer is null, there is no change to the output collection.
I - the type of object in the input collection
O - the type of object in the output collection
R - the type of 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 if inputIterator and transformer are not null
NullPointerException - if the output collection is null and both, inputIterator and transformer are not null
public static <T> boolean addIgnoreNull(Collection<T> collection, T object)
T - the type of object the
Collection contains
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
public static <C> boolean addAll(Collection<C> collection, Iterable <? extends C> iterable)
Iterable to the given collection. If the
Iterable is a
Collection then it is cast and will be added using
Collection.addAll(Collection) instead of iterating.
C - the type of object the
Collection contains
collection - the collection to add to, must not be null
iterable - the iterable of elements to add, must not be null
NullPointerException - if the collection or iterator is null
public static <C> boolean addAll(Collection<C> collection, Iterator <? extends C> iterator)
C - the type of object the
Collection contains
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
public static <C> boolean addAll(Collection<C> collection, Enumeration <? extends C> enumeration)
C - the type of object the
Collection contains
collection - the collection to add to, must not be null
enumeration - the enumeration of elements to add, must not be null
true if the collections was changed,
false otherwise
NullPointerException - if the collection or enumeration is null
public static <C> boolean addAll(Collection<C> collection, C[] elements)
C - the type of object the
Collection contains
collection - the collection to add to, must not be null
elements - the array of elements to add, must not be null
true if the collection was changed,
false otherwise
NullPointerException - if the collection or array is null
@Deprecated public static <T> T get(Iterator<T> iterator, int index)
IteratorUtils.get(Iterator, int) instead
index-th value in
Iterator, throwing
IndexOutOfBoundsException if there is no such element.
The Iterator is advanced to index (or to the end, if index exceeds the number of entries) as a side effect of this method.
T - the type of object in the
Iterator
iterator - the iterator to get a value from
index - the index to get
IndexOutOfBoundsException - if the index is invalid
IllegalArgumentException - if the object type is invalid
@Deprecated public static <T> T get(Iterable<T> iterable, int index)
IterableUtils.get(Iterable, int) instead
index-th value in the
iterable's
Iterator, throwing
IndexOutOfBoundsException if there is no such element.
If the Iterable is a List, then it will use List.
T - the type of object in the
Iterable.
iterable - the
Iterable to get a value from
index - the index to get
IndexOutOfBoundsException - if the index is invalid
public static Objectget(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 from
index - the index to get
IndexOutOfBoundsException - if the index is invalid
IllegalArgumentException - if the object type is invalid
public static <K,V> Map .Entry <K ,V> get(Map <K ,V> map, int index)
index-th
Map.Entry in the
map's
entrySet, throwing
IndexOutOfBoundsException if there is no such element.
K - the key type in the
Map
V - the key type in the
Map
map - the object to get a value from
index - the index to get
IndexOutOfBoundsException - if the index is invalid
public static int size(Objectobject)
This method can handles objects as follows
object - the object to get the size of, may be null
IllegalArgumentException - thrown if object is not recognised
public static boolean sizeIsEmpty(Objectobject)
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, may be null
IllegalArgumentException - thrown if object is not recognised
public static boolean isEmpty(Collection<?> coll)
Null returns true.
coll - the collection to check, may be null
public static boolean isNotEmpty(Collection<?> coll)
Null returns false.
coll - the collection to check, may be null
public static void reverseArray(Object[] array)
array - the array to reverse
public static boolean isFull(Collection<? extends Object > 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 check
NullPointerException - if the collection is null
public static int maxSize(Collection<? extends Object > 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 check
NullPointerException - if the collection is null
public static <O extends Comparable<? super O>> List <O> collate(Iterable <? extends O> a, Iterable <? extends O> b)
Uses the standard O(n) merge algorithm for combining two sorted lists.
O - the element type
a - the first collection, must not be null
b - the second collection, must not be null
NullPointerException - if either collection is null
public static <O extends Comparable<? super O>> List <O> collate(Iterable <? extends O> a, Iterable <? extends O> b, boolean includeDuplicates)
Uses the standard O(n) merge algorithm for combining two sorted lists.
O - the element type
a - the first collection, must not be null
b - the second collection, must not be null
includeDuplicates - if
true duplicate elements will be retained, otherwise they will be removed in the output collection
NullPointerException - if either collection is null
public static <O> List<O> collate(Iterable <? extends O> a, Iterable <? extends O> b, Comparator <? super O> c)
Uses the standard O(n) merge algorithm for combining two sorted lists.
O - the element type
a - the first collection, must not be null
b - the second collection, must not be null
c - the comparator to use for the merge.
NullPointerException - if either collection or the comparator is null
public static <O> List<O> collate(Iterable <? extends O> a, Iterable <? extends O> b, Comparator <? super O> c, boolean includeDuplicates)
Uses the standard O(n) merge algorithm for combining two sorted lists.
O - the element type
a - the first collection, must not be null
b - the second collection, must not be null
c - the comparator to use for the merge.
includeDuplicates - if
true duplicate elements will be retained, otherwise they will be removed in the output collection
NullPointerException - if either collection or the comparator is null
public static <E> Collection<List <E>> permutations(Collection <E> collection)
Collection of all the permutations of the input collection.
NOTE: the number of permutations of a given collection is equal to n!, where n is the size of the collection. Thus, the resulting collection will become very large for collections > 10 (e.g. 10! = 3628800, 15! = 1307674368000).
For larger collections it is advised to use a PermutationIterator to iterate over all permutations.
E - the element type
collection - the collection to create permutations for, may not be null
NullPointerException - if collection is null
PermutationIterator
public static <C> Collection<C> retainAll(Collection <C> collection, 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);.
This implementation iterates over collection, checking each element in turn to see if it's contained in retain. If it's contained, it's added to the returned list. As a consequence, it is advised to use a collection type for retain that provides a fast (e.g. O(1)) implementation of Collection.
C - the type of object the
Collection contains
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
public static <E> Collection<E> retainAll(Iterable <E> collection, Iterable <? extends E> retain, Equator <? super E> equator)
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);.
Moreover this method uses an Equator instead of Object to determine the equality of the elements in collection and retain. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.
E - the type of object the
Collection contains
collection - the collection whose contents are the target of the
retainAll operation
retain - the collection containing the elements to be retained in the returned collection
equator - the Equator used for testing equality
Collection containing all the elements of
collection that occur at least once in
retain according to the
equator
NullPointerException - if any of the parameters is null
public static <E> Collection<E> removeAll(Collection <E> collection, 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);.
This implementation iterates over collection, checking each element in turn to see if it's contained in remove. If it's not contained, it's added to the returned list. As a consequence, it is advised to use a collection type for remove that provides a fast (e.g. O(1)) implementation of Collection.
E - the type of object the
Collection contains
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
public static <E> Collection<E> removeAll(Iterable <E> collection, Iterable <? extends E> remove, Equator <? super E> equator)
remove from
collection. That is, this method returns a collection containing all the elements in
collection 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).
Moreover this method uses an Equator instead of Object to determine the equality of the elements in collection and remove. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.
E - the type of object the
Collection contains
collection - the collection from which items are removed (in the returned collection)
remove - the items to be removed from the returned collection
equator - the Equator used for testing equality
Collection containing all the elements of
collection except any element that if equal according to the
equator
NullPointerException - if any of the parameters is null
@Deprecated public static <C> Collection<C> synchronizedCollection(Collection <C> collection)
Collections.synchronizedCollection(Collection) instead
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.
C - the type of object the
Collection contains
collection - the collection to synchronize, must not be null
NullPointerException - if the collection is null
@Deprecated public static <C> Collection<C> unmodifiableCollection(Collection <? extends C> collection)
Collections.unmodifiableCollection(Collection) instead
This method uses the implementation in the decorators subpackage.
C - the type of object the
Collection contains
collection - the collection to make unmodifiable, must not be null
NullPointerException - if the collection is null
public static <C> Collection<C> predicatedCollection(Collection <C> collection, Predicate <? super C> 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.
C - the type of objects in the Collection.
collection - the collection to predicate, must not be null
predicate - the predicate for the collection, must not be null
NullPointerException - if the Collection is null
public static <E> Collection<E> transformingCollection(Collection <E> collection, Transformer <? super E ,? extends E> 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.
Existing entries in the specified collection will not be transformed. If you want that behaviour, see TransformedCollection.
E - the type of object the
Collection contains
collection - the collection to predicate, must not be null
transformer - the transformer for the collection, must not be null
NullPointerException - if the Collection or Transformer is null
public static <E> E extractSingleton(Collection<E> collection)
E - collection type
collection - to read
NullPointerException - if collection is null
IllegalArgumentException - if collection is empty or contains more than one element