Class CollectionUtils
Collection instances.
Various utility methods might put the input objects into a Set/Map/Bag. In case
the input objects override Object.equals(Object), it is mandatory that
the general contract of the Object.hashCode() method is maintained.
NOTE: From 4.0, method parameters will take Iterable objects when possible.
- Since:
- 1.0
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringA String for Colon (":").static final StringA String for Comma (",").static final StringDefault prefix used while converting an Iterator to its String representation.static final StringDefault suffix used while converting an Iterator to its String representation.static final CollectionAn empty unmodifiable collection.static final intThe index value when an element is not found in a collection or array:-1. -
Method Summary
Modifier and TypeMethodDescriptionstatic <C> booleanaddAll(Collection<C> collection, C... elements) Adds all elements in the array to the given collection.static <C> booleanaddAll(Collection<C> collection, Iterable<? extends C> iterable) Adds all elements in theIterableto the given collection.static <C> booleanaddAll(Collection<C> collection, Enumeration<? extends C> enumeration) Adds all elements in the enumeration to the given collection.static <C> booleanaddAll(Collection<C> collection, Iterator<? extends C> iterator) Adds all elements in the iteration to the given collection.static <T> booleanaddIgnoreNull(Collection<T> collection, T object) Adds an element to the collection unless the element is null.static <O> intcardinality(O obj, Iterable<? super O> collection) Deprecated.static <O extends Comparable<? super O>>
List<O> 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<? super O>>
List<O> 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<O> collate(Iterable<? extends O> a, Iterable<? extends O> b, Comparator<? super O> c) 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<O> collate(Iterable<? extends O> iterableA, Iterable<? extends O> iterableB, Comparator<? super O> comparator, boolean includeDuplicates) 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,O, R extends Collection<? super O>>
Rcollect(Iterable<? extends I> inputCollection, Transformer<? super I, ? extends O> transformer, R outputCollection) Transforms all elements from input collection with the given transformer and adds them to the output collection.static <I,O> Collection <O> collect(Iterable<I> inputCollection, Transformer<? super I, ? extends O> transformer) Returns a new Collection containing all elements of the input collection transformed by the given transformer.static <I,O, R extends Collection<? super O>>
Rcollect(Iterator<? extends I> inputIterator, Transformer<? super I, ? extends O> transformer, R outputCollection) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.static <I,O> Collection <O> collect(Iterator<I> inputIterator, Transformer<? super I, ? extends O> transformer) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.static booleancontainsAll(Collection<?> coll1, Collection<?> coll2) Returnstrueiff all elements ofcoll2are also contained incoll1.static booleancontainsAny(Collection<?> coll1, Collection<?> coll2) Returnstrueiff at least one element is in both collections.static <T> booleancontainsAny(Collection<?> coll1, T... coll2) Returnstrueiff at least one element is in both collections.static <C> intcountMatches(Iterable<C> input, Predicate<? super C> predicate) Deprecated.since 4.1, useIterableUtils.countMatches(Iterable, Predicate)insteadstatic <O> Collection<O> disjunction(Iterable<? extends O> a, Iterable<? extends O> b) Returns aCollectioncontaining the exclusive disjunction (symmetric difference) of the givenIterables.static <T> Collection<T> Returns the immutable EMPTY_COLLECTION with generic type safety.static <T> Collection<T> emptyIfNull(Collection<T> collection) Returns an immutable empty collection if the argument isnull, or the argument itself otherwise.static <C> booleanDeprecated.since 4.1, useIterableUtils.matchesAny(Iterable, Predicate)insteadstatic <E> EextractSingleton(Collection<E> collection) Extract the lone element of the specified Collection.static <T> booleanFilter the collection by applying a Predicate to each element.static <T> booleanfilterInverse(Iterable<T> collection, Predicate<? super T> predicate) Filter the collection by applying a Predicate to each element.static <T> TDeprecated.since 4.1, useIterableUtils.find(Iterable, Predicate)insteadstatic <T,C extends Closure<? super T>>
TforAllButLastDo(Iterable<T> collection, C closure) Deprecated.since 4.1, useIterableUtils.forEachButLast(Iterable, Closure)insteadstatic <T,C extends Closure<? super T>>
TforAllButLastDo(Iterator<T> iterator, C closure) Deprecated.since 4.1, useIteratorUtils.forEachButLast(Iterator, Closure)insteadstatic <T,C extends Closure<? super T>>
CDeprecated.since 4.1, useIterableUtils.forEach(Iterable, Closure)insteadstatic <T,C extends Closure<? super T>>
CDeprecated.since 4.1, useIteratorUtils.forEach(Iterator, Closure)insteadstatic <T> TDeprecated.since 4.1, useIterableUtils.get(Iterable, int)insteadstatic ObjectGets theindex-th value inobject, throwingIndexOutOfBoundsExceptionif there is no such element orIllegalArgumentExceptionifobjectis not an instance of one of the supported types.static <T> TDeprecated.since 4.1, useIteratorUtils.get(Iterator, int)insteadstatic <K,V> Map.Entry <K, V> Gets theindex-thMap.Entryin themap'sentrySet, throwingIndexOutOfBoundsExceptionif there is no such element.getCardinalityMap(Iterable<? extends O> coll) Gets aMapmapping each unique element in the givenCollectionto anIntegerrepresenting the number of occurrences of that element in theCollection.static <E> inthashCode(Collection<? extends E> collection, Equator<? super E> equator) Returns the hash code of the input collection using the hash method of an equator.static <O> Collection<O> intersection(Iterable<? extends O> a, Iterable<? extends O> b) Returns aCollectioncontaining the intersection of the givenIterables.static booleanisEmpty(Collection<?> coll) Null-safe check if the specified collection is empty.static booleanisEqualCollection(Collection<?> a, Collection<?> b) Returnstrueiff the givenCollections contain exactly the same elements with exactly the same cardinalities.static <E> booleanisEqualCollection(Collection<? extends E> a, Collection<? extends E> b, Equator<? super E> equator) Returnstrueiff the givenCollections contain exactly the same elements with exactly the same cardinalities.static booleanisFull(Collection<? extends Object> collection) Returns true if no more elements can be added to the Collection.static booleanisNotEmpty(Collection<?> coll) Null-safe check if the specified collection is not empty.static booleanisProperSubCollection(Collection<?> a, Collection<?> b) Returnstrueiff 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 booleanisSubCollection(Collection<?> a, Collection<?> b) Returnstrueiff 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> booleanmatchesAll(Iterable<C> input, Predicate<? super C> predicate) Deprecated.since 4.1, useIterableUtils.matchesAll(Iterable, Predicate)insteadstatic intmaxSize(Collection<? extends Object> collection) Gets the maximum number of elements that the Collection can contain.static <E> Collection<List<E>> permutations(Collection<E> collection) Returns aCollectionof all the permutations of the input collection.static <C> Collection<C> predicatedCollection(Collection<C> collection, Predicate<? super C> predicate) Returns a predicated (validating) collection backed by the given collection.static <E> Collection<E> Removes all elements inremovefromcollection.static <E> Collection<E> removeAll(Collection<E> collection, Collection<?> remove) Removes the elements inremovefromcollection.static <E> Collection<E> removeCount(Collection<E> input, int startIndex, int count) Removes the specified number of elements from the start index in the collection and returns them.static <E> Collection<E> removeRange(Collection<E> input, int startIndex, int endIndex) Removes elements whose index are between startIndex, inclusive and endIndex, exclusive in the collection and returns them.static <E> Collection<E> Returns a collection containing all the elements incollectionthat are also inretain.static <C> Collection<C> retainAll(Collection<C> collection, Collection<?> retain) Returns a collection containing all the elements incollectionthat are also inretain.static voidreverseArray(Object[] array) Reverses the order of the given array.static <O> Collection<O> Selects all elements from input collection which match the given predicate into an output collection.static <O,R extends Collection<? super O>>
RSelects all elements from input collection which match the given predicate and adds them to outputCollection.static <O,R extends Collection<? super O>>
Rselect(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection, R rejectedCollection) Selects all elements from inputCollection into an output and rejected collection, based on the evaluation of the given predicate.static <O> Collection<O> selectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate) Selects all elements from inputCollection which don't match the given predicate into an output collection.static <O,R extends Collection<? super O>>
RselectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection) Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.static intGets the size of the collection/iterator specified.static booleansizeIsEmpty(Object object) Checks if the specified collection/array/iterator is empty.static <O> Collection<O> Returns a newCollectioncontaining<em>a</em> - <em>b</em>.static <O> Collection<O> Returns a newCollectioncontaining a minus a subset of b.static <C> Collection<C> synchronizedCollection(Collection<C> collection) Deprecated.since 4.1, useCollections.synchronizedCollection(Collection)insteadstatic <C> voidtransform(Collection<C> collection, Transformer<? super C, ? extends C> transformer) Transform the collection by applying a Transformer to each element.static <E> Collection<E> transformingCollection(Collection<E> collection, Transformer<? super E, ? extends E> transformer) Returns a transformed bag backed by the given collection.static <O> Collection<O> Returns aCollectioncontaining the union of the givenIterables.static <C> Collection<C> unmodifiableCollection(Collection<? extends C> collection) Deprecated.since 4.1, useCollections.unmodifiableCollection(Collection)instead
-
Field Details
-
INDEX_NOT_FOUND
The index value when an element is not found in a collection or array:-1.- Since:
- 4.5.0-M1
- See Also:
-
DEFAULT_TOSTRING_PREFIX
Default prefix used while converting an Iterator to its String representation.- Since:
- 4.5.0-M1
- See Also:
-
DEFAULT_TOSTRING_SUFFIX
Default suffix used while converting an Iterator to its String representation.- Since:
- 4.5.0-M1
- See Also:
-
COLON
-
COMMA
-
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.
-
-
Method Details
-
addAll
Adds all elements in the array to the given collection.- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to add to, must not be nullelements- the array of elements to add, must not be null- Returns:
trueif the collection was changed,falseotherwise- Throws:
NullPointerException- if the collection or elements is null
-
addAll
Adds all elements in the enumeration to the given collection.- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to add to, must not be nullenumeration- the enumeration of elements to add, must not be null- Returns:
trueif the collections was changed,falseotherwise- Throws:
NullPointerException- if the collection or enumeration is null
-
addAll
Adds all elements in theIterableto the given collection. If theIterableis aCollectionthen it is cast and will be added usingCollection.addAll(Collection)instead of iterating.- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to add to, must not be nulliterable- the iterable of elements to add, must not be null- Returns:
- a boolean indicating whether the collection has changed or not.
- Throws:
NullPointerException- if the collection or iterable is null
-
addAll
Adds all elements in the iteration to the given collection.- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to add to, must not be nulliterator- the iterator of elements to add, must not be null- Returns:
- a boolean indicating whether the collection has changed or not.
- Throws:
NullPointerException- if the collection or iterator is null
-
addIgnoreNull
Adds an element to the collection unless the element is null.- Type Parameters:
T- the type of object theCollectioncontains- Parameters:
collection- the collection to add to, must not be nullobject- the object to add, if null it will not be added- Returns:
- true if the collection changed
- Throws:
NullPointerException- if the collection is null- Since:
- 3.2
-
cardinality
Deprecated.since 4.1, useIterableUtils.frequency(Iterable, Object)instead. Be aware that the order of parameters has changed.Returns the number of occurrences of obj in coll.- Type Parameters:
O- the type of object that theIterablemay contain.- Parameters:
obj- the object to find the cardinality ofcollection- theIterableto search- Returns:
- the number of occurrences of obj in coll
- Throws:
NullPointerException- if collection is null
-
collate
public static <O extends Comparable<? super O>> List<O> collate(Iterable<? extends O> a, Iterable<? extends O> b) Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.Uses the standard O(n) merge algorithm for combining two sorted lists.
- Type Parameters:
O- the element type- Parameters:
a- the first collection, must not be nullb- the second collection, must not be null- Returns:
- a new sorted List, containing the elements of Collection a and b
- Throws:
NullPointerException- if either collection is null- Since:
- 4.0
-
collate
public static <O extends Comparable<? super O>> List<O> collate(Iterable<? extends O> a, Iterable<? extends O> b, boolean includeDuplicates) Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.Uses the standard O(n) merge algorithm for combining two sorted lists.
- Type Parameters:
O- the element type- Parameters:
a- the first collection, must not be nullb- the second collection, must not be nullincludeDuplicates- iftrueduplicate elements will be retained, otherwise they will be removed in the output collection- Returns:
- a new sorted List, containing the elements of Collection a and b
- Throws:
NullPointerException- if either collection is null- Since:
- 4.0
-
collate
public static <O> List<O> collate(Iterable<? extends O> a, Iterable<? extends O> b, Comparator<? super O> c) 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.Uses the standard O(n) merge algorithm for combining two sorted lists.
- Type Parameters:
O- the element type- Parameters:
a- the first collection, must not be nullb- the second collection, must not be nullc- the comparator to use for the merge.- Returns:
- a new sorted List, containing the elements of Collection a and b
- Throws:
NullPointerException- if either collection or the comparator is null- Since:
- 4.0
-
collate
public static <O> List<O> collate(Iterable<? extends O> iterableA, Iterable<? extends O> iterableB, Comparator<? super O> comparator, boolean includeDuplicates) 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.Uses the standard O(n) merge algorithm for combining two sorted lists.
- Type Parameters:
O- the element type- Parameters:
iterableA- the first collection, must not be nulliterableB- the second collection, must not be nullcomparator- the comparator to use for the merge.includeDuplicates- iftrueduplicate elements will be retained, otherwise they will be removed in the output collection- Returns:
- a new sorted List, containing the elements of Collection a and b
- Throws:
NullPointerException- if either collection or the comparator is null- Since:
- 4.0
-
collect
public static <I,O, R collectR extends Collection<? super O>> (Iterable<? extends I> inputCollection, Transformer<? super I, ? extends O> transformer, R outputCollection) Transforms all elements from input collection with the given transformer and adds them to the output collection.If the input collection or transformer is null, there is no change to the output collection.
- Type Parameters:
I- the type of object in the input collectionO- the type of object in the output collectionR- the type of 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 if inputCollection and transformer are not null- Returns:
- the output collection with the transformed input added
- Throws:
NullPointerException- if the outputCollection is null and both, inputCollection and transformer are not null
-
collect
public static <I,O> Collection<O> collect(Iterable<I> inputCollection, Transformer<? super I, ? extends O> transformer) Returns a new Collection containing all elements of the input collection transformed by the given transformer.If the input collection or transformer is null, the result is an empty list.
- Type Parameters:
I- the type of object in the input collectionO- the type of object in the output collection- 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)
- Throws:
NullPointerException- if the outputCollection is null and both, inputCollection and transformer are not null
-
collect
public static <I,O, R collectR extends Collection<? super O>> (Iterator<? extends I> inputIterator, Transformer<? super I, ? extends O> transformer, R outputCollection) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.If the input iterator or transformer is null, there is no change to the output collection.
- Type Parameters:
I- the type of object in the input collectionO- the type of object in the output collectionR- the type of 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 if inputIterator and transformer are not null- Returns:
- the outputCollection with the transformed input added
- Throws:
NullPointerException- if the output collection is null and both, inputIterator and transformer are not null
-
collect
public static <I,O> Collection<O> collect(Iterator<I> inputIterator, Transformer<? super I, ? extends O> transformer) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.If the input iterator or transformer is null, the result is an empty list.
- Type Parameters:
I- the type of object in the input collectionO- the type of object in the output collection- 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)
-
containsAll
Returnstrueiff all elements ofcoll2are also contained incoll1. The cardinality of values incoll2is not taken into account, which is the same behavior asCollection.containsAll(Collection).In other words, this method returns
trueiff theintersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)of coll1 and coll2 has the same cardinality as the set of unique values fromcoll2. In casecoll2is empty,truewill be returned.This method is intended as a replacement for
Collection.containsAll(Collection)with a guaranteed runtime complexity ofO(n + m). Depending on the type ofCollectionprovided, this method will be much faster than callingCollection.containsAll(Collection)instead, though this will come at the cost of an additional space complexity O(n).- Parameters:
coll1- the first collection, must not be nullcoll2- the second collection, must not be null- Returns:
trueiff the intersection of the collections has the same cardinality as the set of unique elements from the second collection- Throws:
NullPointerException- if coll1 or coll2 is null- Since:
- 4.0
-
containsAny
Returnstrueiff at least one element is in both collections.In other words, this method returns
trueiff theintersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)of coll1 and coll2 is not empty.- Parameters:
coll1- the first collection, must not be nullcoll2- the second collection, must not be null- Returns:
trueiff the intersection of the collections is non-empty- Throws:
NullPointerException- if coll1 or coll2 is null- Since:
- 2.1
- See Also:
-
containsAny
Returnstrueiff at least one element is in both collections.In other words, this method returns
trueiff theintersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)of coll1 and coll2 is not empty.- Type Parameters:
T- the type of object to lookup incoll1.- Parameters:
coll1- the first collection, must not benull.coll2- the second collection, must not benull.- Returns:
trueiff the intersection of the collections is non-empty.- Throws:
NullPointerException- if coll1 or coll2 isnull.- Since:
- 4.2
- See Also:
-
countMatches
Deprecated.since 4.1, useIterableUtils.countMatches(Iterable, Predicate)insteadCounts the number of elements in the input collection that match the predicate.A
nullcollection or predicate matches no elements. -
disjunction
Returns aCollectioncontaining the exclusive disjunction (symmetric difference) of the givenIterables.The cardinality of each element e in the returned
Collectionwill be equal tomax(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)}).- Type Parameters:
O- the generic type that is able to represent the types contained in both input collections.- Parameters:
a- the first collection, must not be nullb- the second collection, must not be null- Returns:
- the symmetric difference of the two collections
- Throws:
NullPointerException- if either collection is null
-
emptyCollection
Returns the immutable EMPTY_COLLECTION with generic type safety.- Type Parameters:
T- the element type- Returns:
- immutable empty collection
- Since:
- 4.0
- See Also:
-
emptyIfNull
Returns an immutable empty collection if the argument isnull, or the argument itself otherwise.- Type Parameters:
T- the element type- Parameters:
collection- the collection, possiblynull- Returns:
- an empty collection if the argument is
null
-
exists
Deprecated.since 4.1, useIterableUtils.matchesAny(Iterable, Predicate)insteadAnswers true if a predicate is true for at least one element of a collection.A
nullcollection or predicate returns false. -
extractSingleton
Extract the lone element of the specified Collection.- Type Parameters:
E- collection type- Parameters:
collection- to read- Returns:
- sole member of collection
- Throws:
NullPointerException- if collection is nullIllegalArgumentException- if collection is empty or contains more than one element- Since:
- 4.0
-
filter
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.
- Type Parameters:
T- the type of object theIterablecontains- Parameters:
collection- the collection to get the input from, may be nullpredicate- the predicate to use as a filter, may be null- Returns:
- true if the collection is modified by this call, false otherwise.
-
filterInverse
Filter the collection by applying a Predicate to each element. If the predicate returns true, remove the element.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.
- Type Parameters:
T- the type of object theIterablecontains- Parameters:
collection- the collection to get the input from, may be nullpredicate- the predicate to use as a filter, may be null- Returns:
- true if the collection is modified by this call, false otherwise.
-
find
Deprecated.since 4.1, useIterableUtils.find(Iterable, Predicate)insteadFinds 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.
- Type Parameters:
T- the type of object theIterablecontains- 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
-
forAllButLastDo
@Deprecated public static <T,C extends Closure<? super T>> T forAllButLastDo(Iterable<T> collection, C closure) Deprecated.since 4.1, useIterableUtils.forEachButLast(Iterable, Closure)insteadExecutes the given closure on each but the last element in the collection.If the input collection or closure is null, there is no change made.
- Type Parameters:
T- the type of object theIterablecontainsC- the closure type- Parameters:
collection- the collection to get the input from, may be nullclosure- the closure to perform, may be null- Returns:
- the last element in the collection, or null if either collection or closure is null
- Since:
- 4.0
-
forAllButLastDo
@Deprecated public static <T,C extends Closure<? super T>> T forAllButLastDo(Iterator<T> iterator, C closure) Deprecated.since 4.1, useIteratorUtils.forEachButLast(Iterator, Closure)insteadExecutes the given closure on each but the last element in the collection.If the input collection or closure is null, there is no change made.
- Type Parameters:
T- the type of object theCollectioncontainsC- the closure type- Parameters:
iterator- the iterator to get the input from, may be nullclosure- the closure to perform, may be null- Returns:
- the last element in the collection, or null if either iterator or closure is null
- Since:
- 4.0
-
forAllDo
@Deprecated public static <T,C extends Closure<? super T>> C forAllDo(Iterable<T> collection, C closure) Deprecated.since 4.1, useIterableUtils.forEach(Iterable, Closure)insteadExecutes the given closure on each element in the collection.If the input collection or closure is null, there is no change made.
- Type Parameters:
T- the type of object theIterablecontainsC- the closure type- Parameters:
collection- the collection to get the input from, may be nullclosure- the closure to perform, may be null- Returns:
- closure
-
forAllDo
@Deprecated public static <T,C extends Closure<? super T>> C forAllDo(Iterator<T> iterator, C closure) Deprecated.since 4.1, useIteratorUtils.forEach(Iterator, Closure)insteadExecutes the given closure on each element in the collection.If the input collection or closure is null, there is no change made.
- Type Parameters:
T- the type of object theIteratorcontainsC- the closure type- Parameters:
iterator- the iterator to get the input from, may be nullclosure- the closure to perform, may be null- Returns:
- closure
- Since:
- 4.0
-
get
Deprecated.since 4.1, useIterableUtils.get(Iterable, int)insteadGets theindex-th value in theiterable'sIterator, throwingIndexOutOfBoundsExceptionif there is no such element.If the
Iterableis aList, then it will useList.get(int).- Type Parameters:
T- the type of object in theIterable.- Parameters:
iterable- theIterableto get a value fromindex- the index to get- Returns:
- the object at the specified index
- Throws:
IndexOutOfBoundsException- if the index is invalid
-
get
Deprecated.since 4.1, useIteratorUtils.get(Iterator, int)insteadGets theindex-th value inIterator, throwingIndexOutOfBoundsExceptionif there is no such element.The Iterator is advanced to
index(or to the end, ifindexexceeds the number of entries) as a side effect of this method.- Type Parameters:
T- the type of object in theIterator- Parameters:
iterator- the iterator to get a value fromindex- the index to get- Returns:
- the object at the specified index
- Throws:
IndexOutOfBoundsException- if the index is invalidIllegalArgumentException- if the object type is invalidNullPointerException- if iterator is null
-
get
Gets theindex-thMap.Entryin themap'sentrySet, throwingIndexOutOfBoundsExceptionif there is no such element.- Type Parameters:
K- the key type in theMapV- the value type in theMap- Parameters:
map- the object to get a value fromindex- the index to get- Returns:
- the object at the specified index
- Throws:
IndexOutOfBoundsException- if the index is invalid
-
get
Gets theindex-th value inobject, throwingIndexOutOfBoundsExceptionif there is no such element orIllegalArgumentExceptionifobjectis not an instance of one of the supported types.The supported types, and associated semantics are:
- Map -- the value returned is the
Map.Entryin positionindexin the map'sentrySetiterator, 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 anIndexOutOfBoundsExceptionis 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, ifindexexceeds 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
- Throws:
IndexOutOfBoundsException- if the index is invalidIllegalArgumentException- if the object type is invalid
- Map -- the value returned is the
-
getCardinalityMap
Gets aMapmapping each unique element in the givenCollectionto anIntegerrepresenting the number of occurrences of that element in theCollection.Only those elements present in the collection will appear as keys in the map.
- Type Parameters:
O- the type of object in the returnedMap. This is a super type of <I>.- Parameters:
coll- the collection to get the cardinality map for, must not be null- Returns:
- the populated cardinality map
- Throws:
NullPointerException- if coll is null
-
hashCode
Returns the hash code of the input collection using the hash method of an equator.Returns 0 if the input collection is
null.- Type Parameters:
E- the element type- Parameters:
collection- the input collectionequator- the equator used for generate hashCode- Returns:
- the hash code of the input collection using the hash method of an equator
- Throws:
NullPointerException- if the equator isnull- Since:
- 4.5.0-M1
-
intersection
Returns aCollectioncontaining the intersection of the givenIterables.The cardinality of each element in the returned
Collectionwill be equal to the minimum of the cardinality of that element in the two givenIterables.- Type Parameters:
O- the generic type that is able to represent the types contained in both input collections.- Parameters:
a- the first collection, must not be nullb- the second collection, must not be null- Returns:
- the intersection of the two collections
- Throws:
NullPointerException- if either collection is null- See Also:
-
isEmpty
Null-safe check if the specified collection is empty.Null returns true.
- Parameters:
coll- the collection to check, may be null- Returns:
- true if empty or null
- Since:
- 3.2
-
isEqualCollection
Returnstrueiff the givenCollections 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:
trueiff the collections contain the same elements with the same cardinalities.- Throws:
NullPointerException- if either collection is null
-
isEqualCollection
public static <E> boolean isEqualCollection(Collection<? extends E> a, Collection<? extends E> b, Equator<? super E> equator) Returnstrueiff the givenCollections 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 (for example by casting to their rawtypes) will result in a
ClassCastExceptionthrown at runtime.- Type Parameters:
E- the element type- Parameters:
a- the first collection, must not be nullb- the second collection, must not be nullequator- the Equator used for testing equality- Returns:
trueiff the collections contain the same elements with the same cardinalities.- Throws:
NullPointerException- if either collection or equator is null- Since:
- 4.0
-
isFull
Returns true if no more elements can be added to the Collection.This method uses the
BoundedCollectioninterface 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:
collection- the collection to check- Returns:
- true if the BoundedCollection is full
- Throws:
NullPointerException- if the collection is null
-
isNotEmpty
Null-safe check if the specified collection is not empty.Null returns false.
- Parameters:
coll- the collection to check, may be null- Returns:
- true if non-null and non-empty
- Since:
- 3.2
-
isProperSubCollection
Returnstrueiff 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() < Integer.MAXVALUE
- Parameters:
a- the first (sub?) collection, must not be nullb- the second (super?) collection, must not be null- Returns:
trueiff a is a proper sub-collection of b- Throws:
NullPointerException- if either collection is null- See Also:
-
isSubCollection
Returnstrueiff 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:
trueiff a is a sub-collection of b- Throws:
NullPointerException- if either collection is null- See Also:
-
matchesAll
Deprecated.since 4.1, useIterableUtils.matchesAll(Iterable, Predicate)insteadAnswers true if a predicate is true for every element of a collection.A
nullpredicate returns false.A
nullor empty collection returns true.- Type Parameters:
C- the type of object theIterablecontains- Parameters:
input- theIterableto get the input from, may be nullpredicate- the predicate to use, may be null- Returns:
- true if every element of the collection matches the predicate or if the collection is empty, false otherwise
- Since:
- 4.0
-
maxSize
Gets the maximum number of elements that the Collection can contain.This method uses the
BoundedCollectioninterface 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:
collection- the collection to check- Returns:
- the maximum size of the BoundedCollection, -1 if no maximum size
- Throws:
NullPointerException- if the collection is null
-
permutations
Returns aCollectionof 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 (for example 10! = 3628800, 15! = 1307674368000).
For larger collections it is advised to use a
PermutationIteratorto iterate over all permutations.- Type Parameters:
E- the element type- Parameters:
collection- the collection to create permutations for, must not be null- Returns:
- an unordered collection of all permutations of the input collection
- Throws:
NullPointerException- if collection is null- Since:
- 4.0
- See Also:
-
predicatedCollection
public static <C> Collection<C> predicatedCollection(Collection<C> collection, Predicate<? super C> 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.
- Type Parameters:
C- the type of objects in the Collection.- 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
- Throws:
NullPointerException- if the collection or predicate is null
-
removeAll
Removes the elements inremovefromcollection. That is, this method returns a collection containing all the elements incthat are not inremove. The cardinality of an elementein the returned collection is the same as the cardinality ofeincollectionunlessremovecontainse, in which case the cardinality is zero. This method is useful if you do not wish to modify the collectioncand thus cannot callcollection.removeAll(remove);.This implementation iterates over
collection, checking each element in turn to see if it's contained inremove. If it's not contained, it's added to the returned list. As a consequence, it is advised to use a collection type forremovethat provides a fast (for example O(1)) implementation ofCollection.contains(Object).- Type Parameters:
E- the type of object theCollectioncontains- Parameters:
collection- the collection from which items are removed (in the returned collection)remove- the items to be removed from the returnedcollection- Returns:
- a
Collectioncontaining all the elements ofcollectionexcept any elements that also occur inremove. - Throws:
NullPointerException- if either parameter is null- Since:
- 4.0 (method existed in 3.2 but was completely broken)
-
removeAll
public static <E> Collection<E> removeAll(Iterable<E> collection, Iterable<? extends E> remove, Equator<? super E> equator) Removes all elements inremovefromcollection. That is, this method returns a collection containing all the elements incollectionthat are not inremove. The cardinality of an elementein the returned collection is the same as the cardinality ofeincollectionunlessremovecontainse, in which case the cardinality is zero. This method is useful if you do not wish to modify the collectioncand thus cannot callcollection.removeAll(remove).Moreover this method uses an
Equatorinstead ofObject.equals(Object)to determine the equality of the elements incollectionandremove. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.- Type Parameters:
E- the type of object theCollectioncontains- Parameters:
collection- the collection from which items are removed (in the returned collection)remove- the items to be removed from the returned collectionequator- the Equator used for testing equality- Returns:
- a
Collectioncontaining all the elements ofcollectionexcept any element that if equal according to theequator - Throws:
NullPointerException- if any of the parameters is null- Since:
- 4.1
-
removeCount
Removes the specified number of elements from the start index in the collection and returns them. This method modifies the input collections.- Type Parameters:
E- the type of object theCollectioncontains- Parameters:
input- the collection will be operated, can't be nullstartIndex- the start index (inclusive) to remove element, can't be less than 0count- the specified number to remove, can't be less than 1- Returns:
- collection of elements that removed from the input collection
- Throws:
NullPointerException- if input is null- Since:
- 4.5.0-M1
-
removeRange
Removes elements whose index are between startIndex, inclusive and endIndex, exclusive in the collection and returns them. This method modifies the input collections.- Type Parameters:
E- the type of object theCollectioncontains- Parameters:
input- the collection will be operated, must not be nullstartIndex- the start index (inclusive) to remove element, must not be less than 0endIndex- the end index (exclusive) to remove, must not be less than startIndex- Returns:
- collection of elements that removed from the input collection
- Throws:
NullPointerException- if input is null- Since:
- 4.5.0-M1
-
retainAll
Returns a collection containing all the elements incollectionthat are also inretain. The cardinality of an elementein the returned collection is the same as the cardinality ofeincollectionunlessretaindoes not containe, in which case the cardinality is zero. This method is useful if you do not wish to modify the collectioncand thus cannot callc.retainAll(retain);.This implementation iterates over
collection, checking each element in turn to see if it's contained inretain. If it's contained, it's added to the returned list. As a consequence, it is advised to use a collection type forretainthat provides a fast (for example O(1)) implementation ofCollection.contains(Object).- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection whose contents are the target of the #retailAll operationretain- the collection containing the elements to be retained in the returned collection- Returns:
- a
Collectioncontaining all the elements ofcollectionthat occur at least once inretain. - Throws:
NullPointerException- if either parameter is null- Since:
- 3.2
-
retainAll
public static <E> Collection<E> retainAll(Iterable<E> collection, Iterable<? extends E> retain, Equator<? super E> equator) Returns a collection containing all the elements incollectionthat are also inretain. The cardinality of an elementein the returned collection is the same as the cardinality ofeincollectionunlessretaindoes not containe, in which case the cardinality is zero. This method is useful if you do not wish to modify the collectioncand thus cannot callc.retainAll(retain);.Moreover this method uses an
Equatorinstead ofObject.equals(Object)to determine the equality of the elements incollectionandretain. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.- Type Parameters:
E- the type of object theCollectioncontains- Parameters:
collection- the collection whose contents are the target of theretainAlloperationretain- the collection containing the elements to be retained in the returned collectionequator- the Equator used for testing equality- Returns:
- a
Collectioncontaining all the elements ofcollectionthat occur at least once inretainaccording to theequator - Throws:
NullPointerException- if any of the parameters is null- Since:
- 4.1
-
reverseArray
Reverses the order of the given array.- Parameters:
array- the array to reverse
-
select
public static <O> Collection<O> select(Iterable<? extends O> inputCollection, Predicate<? super O> predicate) Selects all elements from input collection which match the given predicate into an output collection.A
nullpredicate matches no elements.- Type Parameters:
O- the type of object theIterablecontains- 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)
-
select
public static <O,R extends Collection<? super O>> R select(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R 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.
- Type Parameters:
O- the type of object theIterablecontainsR- the type of the outputCollection- 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 if the inputCollection and predicate or not null- Returns:
- the outputCollection
-
select
public static <O,R extends Collection<? super O>> R select(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection, R rejectedCollection) Selects all elements from inputCollection into an output and rejected collection, based on the evaluation of the given predicate.Elements matching the predicate are added to the
outputCollection, all other elements are added to therejectedCollection.If the input predicate is
null, no elements are added tooutputCollectionorrejectedCollection.Note: calling the method is equivalent to the following code snippet:
select(inputCollection, predicate, outputCollection); selectRejected(inputCollection, predicate, rejectedCollection);
- Type Parameters:
O- the type of object theIterablecontainsR- the type of the outputCollection- Parameters:
inputCollection- the collection to get the input from, may be nullpredicate- the predicate to use, may be nulloutputCollection- the collection to output selected elements into, may not be null if the inputCollection and predicate are not nullrejectedCollection- the collection to output rejected elements into, may not be null if the inputCollection or predicate are not null- Returns:
- the outputCollection
- Since:
- 4.1
-
selectRejected
public static <O> Collection<O> selectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate) 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.- Type Parameters:
O- the type of object theIterablecontains- 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)
-
selectRejected
public static <O,R extends Collection<? super O>> R selectRejected(Iterable<? extends O> inputCollection, Predicate<? super O> predicate, R outputCollection) 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 tooutputCollection.- Type Parameters:
O- the type of object theIterablecontainsR- the type of the outputCollection- 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 if the inputCollection and predicate or not null- Returns:
- outputCollection
-
size
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, may be null- Returns:
- the size of the specified collection or 0 if the object was null
- Throws:
IllegalArgumentException- thrown if object is not recognized- Since:
- 3.1
-
sizeIsEmpty
Checks if the specified collection/array/iterator is empty.This method can handles objects as follows
- Collection - via collection isEmpty
- Map - via map isEmpty
- Array - using array size
- Iterator - via hasNext
- Enumeration - via hasMoreElements
Note: This method is named to avoid clashing with
isEmpty(Collection).- Parameters:
object- the object to get the size of, may be null- Returns:
- true if empty or null
- Throws:
IllegalArgumentException- thrown if object is not recognized- Since:
- 3.2
-
subtract
Returns a newCollectioncontaining<em>a</em> - <em>b</em>. The cardinality of each element e in the returnedCollectionwill be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.- Type Parameters:
O- the generic type that is able to represent the types contained in both input collections.- 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:
-
subtract
public static <O> Collection<O> subtract(Iterable<? extends O> a, Iterable<? extends O> b, Predicate<O> p) Returns a newCollectioncontaining 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
Collectionthat 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
Collectionthat does not satisfy the predicate condition will be equal to the cardinality of e in a.- Type Parameters:
O- the generic type that is able to represent the types contained in both input collections.- Parameters:
a- the collection to subtract from, must not be nullb- the collection to subtract, must not be nullp- the condition used to determine which elements of b are subtracted.- Returns:
- a new collection with the results
- Throws:
NullPointerException- if either collection or p is null- Since:
- 4.0
- See Also:
-
synchronizedCollection
Deprecated.since 4.1, useCollections.synchronizedCollection(Collection)insteadReturns 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.
- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to synchronize, must not be null- Returns:
- a synchronized collection backed by the given collection
- Throws:
NullPointerException- if the collection is null
-
transform
public static <C> void transform(Collection<C> collection, Transformer<? super C, ? extends C> 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.
- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- theCollectionto get the input from, may be nulltransformer- the transformer to perform, may be null
-
transformingCollection
public static <E> Collection<E> transformingCollection(Collection<E> collection, Transformer<? super E, ? extends E> 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.
Existing entries in the specified collection will not be transformed. If you want that behavior, see
TransformedCollection.transformedCollection(java.util.Collection<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>).- Type Parameters:
E- the type of object theCollectioncontains- 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
- Throws:
NullPointerException- if the collection or transformer is null
-
union
Returns aCollectioncontaining the union of the givenIterables.The cardinality of each element in the returned
Collectionwill be equal to the maximum of the cardinality of that element in the two givenIterables.- Type Parameters:
O- the generic type that is able to represent the types contained in both input collections.- Parameters:
a- the first collection, must not be nullb- the second collection, must not be null- Returns:
- the union of the two collections
- Throws:
NullPointerException- if either collection is null- See Also:
-
unmodifiableCollection
@Deprecated public static <C> Collection<C> unmodifiableCollection(Collection<? extends C> collection) Deprecated.since 4.1, useCollections.unmodifiableCollection(Collection)insteadReturns an unmodifiable collection backed by the given collection.This method uses the implementation in the decorators subpackage.
- Type Parameters:
C- the type of object theCollectioncontains- Parameters:
collection- the collection to make unmodifiable, must not be null- Returns:
- an unmodifiable collection backed by the given collection
- Throws:
NullPointerException- if the collection is null
-
IterableUtils.frequency(Iterable, Object)instead.