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 SummaryFieldsModifier 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 SummaryModifier 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_FOUNDThe index value when an element is not found in a collection or array:-1.- Since:
- 4.5.0-M1
- See Also:
 
- 
DEFAULT_TOSTRING_PREFIXDefault prefix used while converting an Iterator to its String representation.- Since:
- 4.5.0-M1
- See Also:
 
- 
DEFAULT_TOSTRING_SUFFIXDefault suffix used while converting an Iterator to its String representation.- Since:
- 4.5.0-M1
- See Also:
 
- 
COLON
- 
COMMA
- 
EMPTY_COLLECTIONAn 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- 
addAllAdds all elements in the array to the given collection.- Type Parameters:
- C- the type of object the- Collectioncontains
- Parameters:
- collection- the collection to add to, must not be null
- elements- 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
 
- 
addAllAdds all elements in the enumeration to the given collection.- Type Parameters:
- C- the type of object the- Collectioncontains
- Parameters:
- collection- the collection to add to, must not be null
- enumeration- 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
 
- 
addAllAdds 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 the- Collectioncontains
- Parameters:
- collection- the collection to add to, must not be null
- iterable- 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
 
- 
addAllAdds all elements in the iteration to the given collection.- Type Parameters:
- C- the type of object the- Collectioncontains
- Parameters:
- collection- the collection to add to, must not be null
- iterator- 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
 
- 
addIgnoreNullAdds an element to the collection unless the element is null.- Type Parameters:
- T- the type of object the- Collectioncontains
- Parameters:
- collection- the collection to add to, must not be null
- object- 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
 
- 
cardinalityDeprecated.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 the- Iterablemay contain.
- Parameters:
- obj- the object to find the cardinality of
- collection- the- Iterableto search
- Returns:
- the number of occurrences of obj in coll
- Throws:
- NullPointerException- if collection is null
 
- 
collatepublic 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 null
- b- 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
 
- 
collatepublic 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 null
- b- the second collection, must not be null
- includeDuplicates- if- trueduplicate 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
 
- 
collatepublic 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 null
- b- the second collection, must not be null
- c- 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
 
- 
collatepublic 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 null
- iterableB- the second collection, must not be null
- comparator- the comparator to use for the merge.
- includeDuplicates- if- trueduplicate 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
 
- 
collectpublic 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 collection
- O- the type of object in the output collection
- R- the type of the output collection
- Parameters:
- 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
- Returns:
- the output collection with the transformed input added
- Throws:
- NullPointerException- if the outputCollection is null and both, inputCollection and transformer are not null
 
- 
collectpublic 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 collection
- O- the type of object in the output collection
- Parameters:
- inputCollection- the collection to get the input from, may not be null
- transformer- 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
 
- 
collectpublic 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 collection
- O- the type of object in the output collection
- R- the type of the output collection
- Parameters:
- 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
- Returns:
- the outputCollection with the transformed input added
- Throws:
- NullPointerException- if the output collection is null and both, inputIterator and transformer are not null
 
- 
collectpublic 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 collection
- O- the type of object in the output collection
- Parameters:
- inputIterator- the iterator to get the input from, may be null
- transformer- the transformer to use, may be null
- Returns:
- the transformed result (new list)
 
- 
containsAllReturnstrueiff 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 null
- coll2- 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
 
- 
containsAnyReturnstrueiff 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 null
- coll2- 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:
 
- 
containsAnyReturnstrueiff 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 in- coll1.
- Parameters:
- coll1- the first collection, must not be- null.
- coll2- 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:
- 4.2
- See Also:
 
- 
countMatchesDeprecated.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.
- 
disjunctionReturns 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 null
- b- the second collection, must not be null
- Returns:
- the symmetric difference of the two collections
- Throws:
- NullPointerException- if either collection is null
 
- 
emptyCollectionReturns the immutable EMPTY_COLLECTION with generic type safety.- Type Parameters:
- T- the element type
- Returns:
- immutable empty collection
- Since:
- 4.0
- See Also:
 
- 
emptyIfNullReturns an immutable empty collection if the argument isnull, or the argument itself otherwise.- Type Parameters:
- T- the element type
- Parameters:
- collection- the collection, possibly- null
- Returns:
- an empty collection if the argument is null
 
- 
existsDeprecated.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.
- 
extractSingletonExtract 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 null
- IllegalArgumentException- if collection is empty or contains more than one element
- Since:
- 4.0
 
- 
filterFilter 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 the- Iterablecontains
- Parameters:
- collection- the collection to get the input from, may be null
- predicate- the predicate to use as a filter, may be null
- Returns:
- true if the collection is modified by this call, false otherwise.
 
- 
filterInverseFilter 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 the- Iterablecontains
- Parameters:
- collection- the collection to get the input from, may be null
- predicate- the predicate to use as a filter, may be null
- Returns:
- true if the collection is modified by this call, false otherwise.
 
- 
findDeprecated.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 the- Iterablecontains
- Parameters:
- collection- the collection to search, may be null
- predicate- 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 the- Iterablecontains
- C- the closure type
- Parameters:
- collection- the collection to get the input from, may be null
- closure- 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 the- Collectioncontains
- C- the closure type
- Parameters:
- iterator- the iterator to get the input from, may be null
- closure- 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 the- Iterablecontains
- C- the closure type
- Parameters:
- collection- the collection to get the input from, may be null
- closure- 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 the- Iteratorcontains
- C- the closure type
- Parameters:
- iterator- the iterator to get the input from, may be null
- closure- the closure to perform, may be null
- Returns:
- closure
- Since:
- 4.0
 
- 
getDeprecated.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 the- Iterable.
- Parameters:
- iterable- the- Iterableto get a value from
- index- the index to get
- Returns:
- the object at the specified index
- Throws:
- IndexOutOfBoundsException- if the index is invalid
 
- 
getDeprecated.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 the- Iterator
- Parameters:
- iterator- the iterator to get a value from
- index- the index to get
- Returns:
- the object at the specified index
- Throws:
- IndexOutOfBoundsException- if the index is invalid
- IllegalArgumentException- if the object type is invalid
- NullPointerException- if iterator is null
 
- 
getGets theindex-thMap.Entryin themap'sentrySet, throwingIndexOutOfBoundsExceptionif there is no such element.- Type Parameters:
- K- the key type in the- Map
- V- the value type in the- Map
- Parameters:
- map- the object to get a value from
- index- the index to get
- Returns:
- the object at the specified index
- Throws:
- IndexOutOfBoundsException- if the index is invalid
 
- 
getGets 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 from
- index- the index to get
- Returns:
- the object at the specified index
- Throws:
- IndexOutOfBoundsException- if the index is invalid
- IllegalArgumentException- if the object type is invalid
 
-  Map -- the value returned is the 
- 
getCardinalityMapGets 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 returned- Map. 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
 
- 
hashCodeReturns 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 collection
- equator- 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 is- null
- Since:
- 4.5.0-M1
 
- 
intersectionReturns 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 null
- b- the second collection, must not be null
- Returns:
- the intersection of the two collections
- Throws:
- NullPointerException- if either collection is null
- See Also:
 
- 
isEmptyNull-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
 
- 
isEqualCollectionReturnstrueiff 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 null
- b- 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
 
- 
isEqualCollectionpublic 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 null
- b- the second collection, must not be null
- equator- 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
 
- 
isFullReturns 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
 
- 
isNotEmptyNull-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
 
- 
isProperSubCollectionReturnstrueiff a is a proper sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a, and there is at least one element f such that the cardinality of f in b is strictly greater than the cardinality of f in a.The implementation assumes - a.size()and- b.size()represent the total cardinality of a and b, resp.
- a.size() < Integer.MAXVALUE
 - Parameters:
- a- the first (sub?) collection, must not be null
- b- 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:
 
- 
isSubCollectionReturnstrueiff 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 null
- b- 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:
 
- 
matchesAllDeprecated.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 the- Iterablecontains
- Parameters:
- input- the- Iterableto get the input from, may be null
- predicate- 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
 
- 
maxSizeGets 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
 
- 
permutationsReturns 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:
 
- 
predicatedCollectionpublic 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 null
- predicate- 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
 
- 
removeAllRemoves 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 the- Collectioncontains
- Parameters:
- collection- the collection from which items are removed (in the returned collection)
- remove- the items to be removed from the returned- collection
- 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)
 
- 
removeAllpublic 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 the- Collectioncontains
- Parameters:
- 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
- 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
 
- 
removeCountRemoves 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 the- Collectioncontains
- Parameters:
- input- the collection will be operated, can't be null
- startIndex- the start index (inclusive) to remove element, can't be less than 0
- count- 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
 
- 
removeRangeRemoves 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 the- Collectioncontains
- Parameters:
- input- the collection will be operated, must not be null
- startIndex- the start index (inclusive) to remove element, must not be less than 0
- endIndex- 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
 
- 
retainAllReturns 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 the- Collectioncontains
- Parameters:
- 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
- Returns:
- a Collectioncontaining all the elements ofcollectionthat occur at least once inretain.
- Throws:
- NullPointerException- if either parameter is null
- Since:
- 3.2
 
- 
retainAllpublic 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 the- Collectioncontains
- Parameters:
- collection- the collection whose contents are the target of the- retainAlloperation
- retain- the collection containing the elements to be retained in the returned collection
- equator- 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
 
- 
reverseArrayReverses the order of the given array.- Parameters:
- array- the array to reverse
 
- 
selectpublic 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 the- Iterablecontains
- Parameters:
- inputCollection- the collection to get the input from, may not be null
- predicate- the predicate to use, may be null
- Returns:
- the elements matching the predicate (new list)
 
- 
selectpublic 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 the- Iterablecontains
- R- the type of the output- Collection
- Parameters:
- 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
- Returns:
- the outputCollection
 
- 
selectpublic 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 the- Iterablecontains
- R- the type of the output- Collection
- Parameters:
- 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
- Returns:
- the outputCollection
- Since:
- 4.1
 
- 
selectRejectedpublic 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 the- Iterablecontains
- Parameters:
- inputCollection- the collection to get the input from, may not be null
- predicate- the predicate to use, may be null
- Returns:
- the elements not matching the predicate (new list)
 
- 
selectRejectedpublic 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 the- Iterablecontains
- R- the type of the output- Collection
- Parameters:
- 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
- Returns:
- outputCollection
 
- 
sizeGets 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
 
- 
sizeIsEmptyChecks 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
 
- 
subtractReturns 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 null
- b- the collection to subtract, must not be null
- Returns:
- a new collection with the results
- See Also:
 
- 
subtractpublic 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 null
- b- the collection to subtract, must not be null
- p- 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:
 
- 
synchronizedCollectionDeprecated.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 the- Collectioncontains
- 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
 
- 
transformpublic 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 the- Collectioncontains
- Parameters:
- collection- the- Collectionto get the input from, may be null
- transformer- the transformer to perform, may be null
 
- 
transformingCollectionpublic 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 the- Collectioncontains
- Parameters:
- collection- the collection to predicate, must not be null
- transformer- 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
 
- 
unionReturns 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 null
- b- 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 the- Collectioncontains
- 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.