org.apache.commons.collections4

Class CollectionUtils

java.lang.Object

org.apache.commons.collections4.CollectionUtils

public class CollectionUtils
extends java.lang.Object

Provides utility methods and decorators for 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

Fields

Modifier and Type	Field and Description
static java.util.Collection	EMPTY_COLLECTION An empty unmodifiable collection.

Method Summary

Modifier and Type	Method and Description
static <C> boolean	addAll(java.util.Collection<C> collection, C[] elements) Adds all elements in the array to the given collection.
static <C> boolean	addAll(java.util.Collection<C> collection, java.util.Enumeration<? extends C> enumeration) Adds all elements in the enumeration to the given collection.
static <C> boolean	addAll(java.util.Collection<C> collection, java.lang.Iterable<? extends C> iterable) Adds all elements in the Iterable to the given collection.
static <C> boolean	addAll(java.util.Collection<C> collection, java.util.Iterator<? extends C> iterator) Adds all elements in the iteration to the given collection.
static <T> boolean	addIgnoreNull(java.util.Collection<T> collection, T object) Adds an element to the collection unless the element is null.
static <O> int	cardinality(O obj, java.lang.Iterable<? super O> coll) Deprecated. since 4.1, use IterableUtils.frequency(Iterable, Object) instead. Be aware that the order of parameters has changed.
static <O extends java.lang.Comparable<? super O>> java.util.List<O>	collate(java.lang.Iterable<? extends O> a, java.lang.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.
static <O extends java.lang.Comparable<? super O>> java.util.List<O>	collate(java.lang.Iterable<? extends O> a, java.lang.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.
static <O> java.util.List<O>	collate(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b, java.util.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> java.util.List<O>	collate(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b, java.util.Comparator<? super O> c, 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 java.util.Collection<? super O>> R	collect(java.lang.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> java.util.Collection<O>	collect(java.lang.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 java.util.Collection<? super O>> R	collect(java.util.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> java.util.Collection<O>	collect(java.util.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 boolean	containsAll(java.util.Collection<?> coll1, java.util.Collection<?> coll2) Returns true iff all elements of coll2 are also contained in coll1.
static boolean	containsAny(java.util.Collection<?> coll1, java.util.Collection<?> coll2) Returns true iff at least one element is in both collections.
static <C> int	countMatches(java.lang.Iterable<C> input, Predicate<? super C> predicate) Deprecated. since 4.1, use IterableUtils.countMatches(Iterable, Predicate) instead
static <O> java.util.Collection<O>	disjunction(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b) Returns a Collection containing the exclusive disjunction (symmetric difference) of the given Iterables.
static <T> java.util.Collection<T>	emptyCollection() Returns the immutable EMPTY_COLLECTION with generic type safety.
static <T> java.util.Collection<T>	emptyIfNull(java.util.Collection<T> collection) Returns an immutable empty collection if the argument is null, or the argument itself otherwise.
static <C> boolean	exists(java.lang.Iterable<C> input, Predicate<? super C> predicate) Deprecated. since 4.1, use IterableUtils.matchesAny(Iterable, Predicate) instead
static <E> E	extractSingleton(java.util.Collection<E> collection) Extract the lone element of the specified Collection.
static <T> boolean	filter(java.lang.Iterable<T> collection, Predicate<? super T> predicate) Filter the collection by applying a Predicate to each element.
static <T> boolean	filterInverse(java.lang.Iterable<T> collection, Predicate<? super T> predicate) Filter the collection by applying a Predicate to each element.
static <T> T	find(java.lang.Iterable<T> collection, Predicate<? super T> predicate) Deprecated. since 4.1, use IterableUtils.find(Iterable, Predicate) instead
static <T,C extends Closure<? super T>> T	forAllButLastDo(java.lang.Iterable<T> collection, C closure) Deprecated. since 4.1, use IterableUtils.forEachButLast(Iterable, Closure) instead
static <T,C extends Closure<? super T>> T	forAllButLastDo(java.util.Iterator<T> iterator, C closure) Deprecated. since 4.1, use IteratorUtils.forEachButLast(Iterator, Closure) instead
static <T,C extends Closure<? super T>> C	forAllDo(java.lang.Iterable<T> collection, C closure) Deprecated. since 4.1, use IterableUtils.forEach(Iterable, Closure) instead
static <T,C extends Closure<? super T>> C	forAllDo(java.util.Iterator<T> iterator, C closure) Deprecated. since 4.1, use IteratorUtils.forEach(Iterator, Closure) instead
static <T> T	get(java.lang.Iterable<T> iterable, int index) Deprecated. since 4.1, use IterableUtils.get(Iterable, int) instead
static <T> T	get(java.util.Iterator<T> iterator, int index) Deprecated. since 4.1, use IteratorUtils.get(Iterator, int) instead
static <K,V> java.util.Map.Entry<K,V>	get(java.util.Map<K,V> map, int index) Returns the index-th Map.Entry in the map's entrySet, throwing IndexOutOfBoundsException if there is no such element.
static java.lang.Object	get(java.lang.Object object, int index) Returns the index-th value in object, throwing IndexOutOfBoundsException if there is no such element or IllegalArgumentException if object is not an instance of one of the supported types.
static <O> java.util.Map<O,java.lang.Integer>	getCardinalityMap(java.lang.Iterable<? extends O> coll) Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurrences of that element in the Collection.
static <O> java.util.Collection<O>	intersection(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b) Returns a Collection containing the intersection of the given Iterables.
static boolean	isEmpty(java.util.Collection<?> coll) Null-safe check if the specified collection is empty.
static boolean	isEqualCollection(java.util.Collection<?> a, java.util.Collection<?> b) Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.
static <E> boolean	isEqualCollection(java.util.Collection<? extends E> a, java.util.Collection<? extends E> b, Equator<? super E> equator) Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.
static boolean	isFull(java.util.Collection<? extends java.lang.Object> coll) Returns true if no more elements can be added to the Collection.
static boolean	isNotEmpty(java.util.Collection<?> coll) Null-safe check if the specified collection is not empty.
static boolean	isProperSubCollection(java.util.Collection<?> a, java.util.Collection<?> b) Returns true iff a is a proper sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a, and there is at least one element f such that the cardinality of f in b is strictly greater than the cardinality of f in a.
static boolean	isSubCollection(java.util.Collection<?> a, java.util.Collection<?> b) Returns true iff a is a sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a.
static <C> boolean	matchesAll(java.lang.Iterable<C> input, Predicate<? super C> predicate) Deprecated. since 4.1, use IterableUtils.matchesAll(Iterable, Predicate) instead
static int	maxSize(java.util.Collection<? extends java.lang.Object> coll) Get the maximum number of elements that the Collection can contain.
static <E> java.util.Collection<java.util.List<E>>	permutations(java.util.Collection<E> collection) Returns a Collection of all the permutations of the input collection.
static <C> java.util.Collection<C>	predicatedCollection(java.util.Collection<C> collection, Predicate<? super C> predicate) Returns a predicated (validating) collection backed by the given collection.
static <E> java.util.Collection<E>	removeAll(java.util.Collection<E> collection, java.util.Collection<?> remove) Removes the elements in remove from collection.
static <E> java.util.Collection<E>	removeAll(java.lang.Iterable<E> collection, java.lang.Iterable<? extends E> remove, Equator<? super E> equator) Removes all elements in remove from collection.
static <C> java.util.Collection<C>	retainAll(java.util.Collection<C> collection, java.util.Collection<?> retain) Returns a collection containing all the elements in collection that are also in retain.
static <E> java.util.Collection<E>	retainAll(java.lang.Iterable<E> collection, java.lang.Iterable<? extends E> retain, Equator<? super E> equator) Returns a collection containing all the elements in collection that are also in retain.
static void	reverseArray(java.lang.Object[] array) Reverses the order of the given array.
static <O> java.util.Collection<O>	select(java.lang.Iterable<? extends O> inputCollection, Predicate<? super O> predicate) Selects all elements from input collection which match the given predicate into an output collection.
static <O,R extends java.util.Collection<? super O>> R	select(java.lang.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.
static <O,R extends java.util.Collection<? super O>> R	select(java.lang.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> java.util.Collection<O>	selectRejected(java.lang.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 java.util.Collection<? super O>> R	selectRejected(java.lang.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 int	size(java.lang.Object object) Gets the size of the collection/iterator specified.
static boolean	sizeIsEmpty(java.lang.Object object) Checks if the specified collection/array/iterator is empty.
static <O> java.util.Collection<O>	subtract(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b) Returns a new Collection containing <i>a</i> - <i>b</i>.
static <O> java.util.Collection<O>	subtract(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b, Predicate<O> p) Returns a new Collection containing a minus a subset of b.
static <C> java.util.Collection<C>	synchronizedCollection(java.util.Collection<C> collection) Deprecated. since 4.1, use Collections.synchronizedCollection(Collection) instead
static <C> void	transform(java.util.Collection<C> collection, Transformer<? super C,? extends C> transformer) Transform the collection by applying a Transformer to each element.
static <E> java.util.Collection<E>	transformingCollection(java.util.Collection<E> collection, Transformer<? super E,? extends E> transformer) Returns a transformed bag backed by the given collection.
static <O> java.util.Collection<O>	union(java.lang.Iterable<? extends O> a, java.lang.Iterable<? extends O> b) Returns a Collection containing the union of the given Iterables.
static <C> java.util.Collection<C>	unmodifiableCollection(java.util.Collection<? extends C> collection) Deprecated. since 4.1, use Collections.unmodifiableCollection(Collection) instead

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EMPTY_COLLECTION

public static final java.util.Collection EMPTY_COLLECTION

An empty unmodifiable collection. The JDK provides empty Set and List implementations which could be used for this purpose. However they could be cast to Set or List which might be undesirable. This implementation only implements Collection.

Method Detail

emptyCollection

public static <T> java.util.Collection<T> 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:

EMPTY_COLLECTION

emptyIfNull

public static <T> java.util.Collection<T> emptyIfNull(java.util.Collection<T> collection)

Returns an immutable empty collection if the argument is null, 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

union

public static <O> java.util.Collection<O> union(java.lang.Iterable<? extends O> a,
                                                java.lang.Iterable<? extends O> b)

Returns a Collection containing the union of the given Iterables.

The cardinality of each element in the returned Collection will be equal to the maximum of the cardinality of that element in the two given Iterables.

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

See Also:

Collection.addAll(java.util.Collection<? extends E>)

intersection

public static <O> java.util.Collection<O> intersection(java.lang.Iterable<? extends O> a,
                                                       java.lang.Iterable<? extends O> b)

Returns a Collection containing the intersection of the given Iterables.

The cardinality of each element in the returned Collection will be equal to the minimum of the cardinality of that element in the two given Iterables.

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

See Also:

Collection.retainAll(java.util.Collection<?>), containsAny(java.util.Collection<?>, java.util.Collection<?>)

disjunction

public static <O> java.util.Collection<O> disjunction(java.lang.Iterable<? extends O> a,
                                                      java.lang.Iterable<? extends O> b)

Returns a Collection containing the exclusive disjunction (symmetric difference) of the given Iterables.

The cardinality of each element e in the returned Collection will be equal to max(cardinality(e,a),cardinality(e,b)) - min(cardinality(e,a), cardinality(e,b)).

This is equivalent to {@link #subtract subtract}({@link #union union(a,b)},{@link #intersection intersection(a,b)}) or {@link #union union}({@link #subtract subtract(a,b)},{@link #subtract subtract(b,a)}).

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

subtract

public static <O> java.util.Collection<O> subtract(java.lang.Iterable<? extends O> a,
                                                   java.lang.Iterable<? extends O> b)

Returns a new Collection containing <i>a</i> - <i>b</i>. The cardinality of each element e in the returned Collection will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.

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:

Collection.removeAll(java.util.Collection<?>)

subtract

public static <O> java.util.Collection<O> subtract(java.lang.Iterable<? extends O> a,
                                                   java.lang.Iterable<? extends O> b,
                                                   Predicate<O> p)

Returns a new Collection containing a minus a subset of b. Only the elements of b that satisfy the predicate condition, p are subtracted from a.

The cardinality of each element e in the returned Collection that satisfies the predicate condition will be the cardinality of e in a minus the cardinality of e in b, or zero, whichever is greater.

The cardinality of each element e in the returned Collection that does not satisfy the predicate condition will be equal to the cardinality of e in a.

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

Since:

4.0

See Also:

Collection.removeAll(java.util.Collection<?>)

containsAll

public static boolean containsAll(java.util.Collection<?> coll1,
                                  java.util.Collection<?> coll2)

Returns true iff all elements of coll2 are also contained in coll1. The cardinality of values in coll2 is not taken into account, which is the same behavior as Collection.containsAll(Collection).

In other words, this method returns true iff the intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>) of coll1 and coll2 has the same cardinality as the set of unique values from coll2. In case coll2 is empty, true will be returned.

This method is intended as a replacement for Collection.containsAll(Collection) with a guaranteed runtime complexity of O(n + m). Depending on the type of Collection provided, this method will be much faster than calling Collection.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:

true iff the intersection of the collections has the same cardinality as the set of unique elements from the second collection

Since:

4.0

containsAny

public static boolean containsAny(java.util.Collection<?> coll1,
                                  java.util.Collection<?> coll2)

Returns true iff at least one element is in both collections.

In other words, this method returns true iff the intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>) of coll1 and coll2 is not empty.

Parameters:

coll1 - the first collection, must not be null

coll2 - the second collection, must not be null

Returns:

true iff the intersection of the collections is non-empty

Since:

2.1

See Also:

intersection(java.lang.Iterable<? extends O>, java.lang.Iterable<? extends O>)

getCardinalityMap

public static <O> java.util.Map<O,java.lang.Integer> getCardinalityMap(java.lang.Iterable<? extends O> coll)

Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurrences of that element in the Collection.

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 .

Parameters:

coll - the collection to get the cardinality map for, must not be null

Returns:

the populated cardinality map

isSubCollection

public static boolean isSubCollection(java.util.Collection<?> a,
                                      java.util.Collection<?> b)

Returns true iff a is a sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a.

Parameters:

a - the first (sub?) collection, must not be null

b - the second (super?) collection, must not be null

Returns:

true iff a is a sub-collection of b

See Also:

isProperSubCollection(java.util.Collection<?>, java.util.Collection<?>), Collection.containsAll(java.util.Collection<?>)

isProperSubCollection

public static boolean isProperSubCollection(java.util.Collection<?> a,
                                            java.util.Collection<?> b)

Returns true iff a is a proper sub-collection of b, that is, iff the cardinality of e in a is less than or equal to the cardinality of e in b, for each element e in a, and there is at least one element f such that the cardinality of f in b is strictly greater than the cardinality of f in a.

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:

true iff a is a proper sub-collection of b

See Also:

isSubCollection(java.util.Collection<?>, java.util.Collection<?>), Collection.containsAll(java.util.Collection<?>)

isEqualCollection

public static boolean isEqualCollection(java.util.Collection<?> a,
                                        java.util.Collection<?> b)

Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.

That is, iff the cardinality of e in a is equal to the cardinality of e in b, for each element e in a or b.

Parameters:

a - the first collection, must not be null

b - the second collection, must not be null

Returns:

true iff the collections contain the same elements with the same cardinalities.

isEqualCollection

public static <E> boolean isEqualCollection(java.util.Collection<? extends E> a,
                                            java.util.Collection<? extends E> b,
                                            Equator<? super E> equator)

Returns true iff the given Collections contain exactly the same elements with exactly the same cardinalities.

That is, iff the cardinality of e in a is equal to the cardinality of e in b, for each element e in a or b.

Note: from version 4.1 onwards this method requires the input collections and equator to be of compatible type (using bounded wildcards). Providing incompatible arguments (e.g. by casting to their rawtypes) will result in a ClassCastException thrown at runtime.

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:

true iff the collections contain the same elements with the same cardinalities.

Throws:

java.lang.NullPointerException - if the equator is null

Since:

4.0

cardinality

@Deprecated
public static <O> int cardinality(O obj,
                                              java.lang.Iterable<? super O> coll)

Deprecated. since 4.1, use IterableUtils.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 Iterable may contain.

Parameters:

obj - the object to find the cardinality of

coll - the Iterable to search

Returns:

the the number of occurrences of obj in coll

Throws:

java.lang.NullPointerException - if coll is null

find

@Deprecated
public static <T> T find(java.lang.Iterable<T> collection,
                                     Predicate<? super T> predicate)

Deprecated. since 4.1, use IterableUtils.find(Iterable, Predicate) instead

Finds the first element in the given collection which matches the given predicate.

If the input collection or predicate is null, or no element of the collection matches the predicate, null is returned.

Type Parameters:

T - the type of object the Iterable contains

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

forAllDo

@Deprecated
public static <T,C extends Closure<? super T>> C forAllDo(java.lang.Iterable<T> collection,
                                                                      C closure)

Deprecated. since 4.1, use IterableUtils.forEach(Iterable, Closure) instead

Executes 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 Iterable contains

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(java.util.Iterator<T> iterator,
                                                                      C closure)

Deprecated. since 4.1, use IteratorUtils.forEach(Iterator, Closure) instead

Executes 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 Iterator contains

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

forAllButLastDo

@Deprecated
public static <T,C extends Closure<? super T>> T forAllButLastDo(java.lang.Iterable<T> collection,
                                                                             C closure)

Deprecated. since 4.1, use IterableUtils.forEachButLast(Iterable, Closure) instead

Executes 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 Iterable contains

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(java.util.Iterator<T> iterator,
                                                                             C closure)

Deprecated. since 4.1, use IteratorUtils.forEachButLast(Iterator, Closure) instead

Executes 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 Collection contains

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

filter

public static <T> boolean filter(java.lang.Iterable<T> collection,
                                 Predicate<? super T> predicate)

Filter the collection by applying a Predicate to each element. If the predicate returns false, remove the element.

If the input collection or predicate is null, there is no change made.

Type Parameters:

T - the type of object the Iterable contains

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.

filterInverse

public static <T> boolean filterInverse(java.lang.Iterable<T> collection,
                                        Predicate<? super T> predicate)

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 the Iterable contains

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.

transform

public static <C> void transform(java.util.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 Collection contains

Parameters:

collection - the Collection to get the input from, may be null

transformer - the transformer to perform, may be null

countMatches

@Deprecated
public static <C> int countMatches(java.lang.Iterable<C> input,
                                               Predicate<? super C> predicate)

Deprecated. since 4.1, use IterableUtils.countMatches(Iterable, Predicate) instead

Counts the number of elements in the input collection that match the predicate.

A null collection or predicate matches no elements.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to get the input from, may be null

predicate - the predicate to use, may be null

Returns:

the number of matches for the predicate in the collection

exists

@Deprecated
public static <C> boolean exists(java.lang.Iterable<C> input,
                                             Predicate<? super C> predicate)

Deprecated. since 4.1, use IterableUtils.matchesAny(Iterable, Predicate) instead

Answers true if a predicate is true for at least one element of a collection.

A null collection or predicate returns false.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to get the input from, may be null

predicate - the predicate to use, may be null

Returns:

true if at least one element of the collection matches the predicate

matchesAll

@Deprecated
public static <C> boolean matchesAll(java.lang.Iterable<C> input,
                                                 Predicate<? super C> predicate)

Deprecated. since 4.1, use IterableUtils.matchesAll(Iterable, Predicate) instead

Answers true if a predicate is true for every element of a collection.

A null predicate returns false.
A null or empty collection returns true.

Type Parameters:

C - the type of object the Iterable contains

Parameters:

input - the Iterable to 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

select

public static <O> java.util.Collection<O> select(java.lang.Iterable<? extends O> inputCollection,
                                                 Predicate<? super O> predicate)

Selects all elements from input collection which match the given predicate into an output collection.

A null predicate matches no elements.

Type Parameters:

O - the type of object the Iterable contains

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)

Throws:

java.lang.NullPointerException - if the input collection is null

select

public static <O,R extends java.util.Collection<? super O>> R select(java.lang.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 Iterable contains

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

select

public static <O,R extends java.util.Collection<? super O>> R select(java.lang.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 the rejectedCollection.

If the input predicate is null, no elements are added to outputCollection or rejectedCollection.

Note: calling the method is equivalent to the following code snippet:

   select(inputCollection, predicate, outputCollection);
   selectRejected(inputCollection, predicate, rejectedCollection);
 

Type Parameters:

O - the type of object the Iterable contains

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

selectRejected

public static <O> java.util.Collection<O> selectRejected(java.lang.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 Iterable contains

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)

Throws:

java.lang.NullPointerException - if the input collection is null

selectRejected

public static <O,R extends java.util.Collection<? super O>> R selectRejected(java.lang.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 to outputCollection.

Type Parameters:

O - the type of object the Iterable contains

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

collect

public static <I,O> java.util.Collection<O> collect(java.lang.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:

java.lang.NullPointerException - if the input collection is null

collect

public static <I,O> java.util.Collection<O> collect(java.util.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)

collect

public static <I,O,R extends java.util.Collection<? super O>> R collect(java.lang.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:

java.lang.NullPointerException - if the outputCollection is null and both, inputCollection and transformer are not null

collect

public static <I,O,R extends java.util.Collection<? super O>> R collect(java.util.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:

java.lang.NullPointerException - if the output collection is null and both, inputIterator and transformer are not null

addIgnoreNull

public static <T> boolean addIgnoreNull(java.util.Collection<T> collection,
                                        T object)

Adds an element to the collection unless the element is null.

Type Parameters:

T - the type of object the Collection contains

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:

java.lang.NullPointerException - if the collection is null

Since:

3.2

addAll

public static <C> boolean addAll(java.util.Collection<C> collection,
                                 java.lang.Iterable<? extends C> iterable)

Adds all elements in the Iterable to the given collection. If the Iterable is a Collection then it is cast and will be added using Collection.addAll(Collection) instead of iterating.

Type Parameters:

C - the type of object the Collection contains

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:

java.lang.NullPointerException - if the collection or iterator is null

addAll

public static <C> boolean addAll(java.util.Collection<C> collection,
                                 java.util.Iterator<? extends C> iterator)

Adds all elements in the iteration to the given collection.

Type Parameters:

C - the type of object the Collection contains

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:

java.lang.NullPointerException - if the collection or iterator is null

addAll

public static <C> boolean addAll(java.util.Collection<C> collection,
                                 java.util.Enumeration<? extends C> enumeration)

Adds all elements in the enumeration to the given collection.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

enumeration - the enumeration of elements to add, must not be null

Returns:

true if the collections was changed, false otherwise

Throws:

java.lang.NullPointerException - if the collection or enumeration is null

addAll

public static <C> boolean addAll(java.util.Collection<C> collection,
                                 C[] elements)

Adds all elements in the array to the given collection.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to add to, must not be null

elements - the array of elements to add, must not be null

Returns:

true if the collection was changed, false otherwise

Throws:

java.lang.NullPointerException - if the collection or array is null

get

@Deprecated
public static <T> T get(java.util.Iterator<T> iterator,
                                    int index)

Deprecated. since 4.1, use IteratorUtils.get(Iterator, int) instead

Returns the index-th value in Iterator, throwing IndexOutOfBoundsException if there is no such element.

The Iterator is advanced to index (or to the end, if index exceeds the number of entries) as a side effect of this method.

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:

java.lang.IndexOutOfBoundsException - if the index is invalid

java.lang.IllegalArgumentException - if the object type is invalid

get

@Deprecated
public static <T> T get(java.lang.Iterable<T> iterable,
                                    int index)

Deprecated. since 4.1, use IterableUtils.get(Iterable, int) instead

Returns the index-th value in the iterable's Iterator, throwing IndexOutOfBoundsException if there is no such element.

If the Iterable is a List, then it will use List.get(int).

Type Parameters:

T - the type of object in the Iterable.

Parameters:

iterable - the Iterable to get a value from

index - the index to get

Returns:

the object at the specified index

Throws:

java.lang.IndexOutOfBoundsException - if the index is invalid

get

public static java.lang.Object get(java.lang.Object object,
                                   int index)

Returns the index-th value in object, throwing IndexOutOfBoundsException if there is no such element or IllegalArgumentException if object is not an instance of one of the supported types.

The supported types, and associated semantics are:

• Map -- the value returned is the Map.Entry in position index in the map's entrySet iterator, if there is such an entry.
• List -- this method is equivalent to the list's get method.
• Array -- the index-th array entry is returned, if there is such an entry; otherwise an IndexOutOfBoundsException is thrown.
• Collection -- the value returned is the index-th object returned by the collection's default iterator, if there is such an element.
• Iterator or Enumeration -- the value returned is the index-th object in the Iterator/Enumeration, if there is such an element. The Iterator/Enumeration is advanced to index (or to the end, if index exceeds 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:

java.lang.IndexOutOfBoundsException - if the index is invalid

java.lang.IllegalArgumentException - if the object type is invalid

get

public static <K,V> java.util.Map.Entry<K,V> get(java.util.Map<K,V> map,
                                                 int index)

Returns the index-th Map.Entry in the map's entrySet, throwing IndexOutOfBoundsException if there is no such element.

Type Parameters:

K - the key type in the Map

V - the key 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:

java.lang.IndexOutOfBoundsException - if the index is invalid

size

public static int size(java.lang.Object object)

Gets the size of the collection/iterator specified.

This method can handles objects as follows

• Collection - the collection size
• Map - the map size
• Array - the array size
• Iterator - the number of elements remaining in the iterator
• Enumeration - the number of elements remaining in the enumeration

Parameters:

object - the object to get the size of, may be null

Returns:

the size of the specified collection or 0 if the object was null

Throws:

java.lang.IllegalArgumentException - thrown if object is not recognised

Since:

3.1

sizeIsEmpty

public static boolean sizeIsEmpty(java.lang.Object object)

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:

java.lang.IllegalArgumentException - thrown if object is not recognised

Since:

3.2

isEmpty

public static boolean isEmpty(java.util.Collection<?> coll)

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

isNotEmpty

public static boolean isNotEmpty(java.util.Collection<?> coll)

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

reverseArray

public static void reverseArray(java.lang.Object[] array)

Reverses the order of the given array.

Parameters:

array - the array to reverse

isFull

public static boolean isFull(java.util.Collection<? extends java.lang.Object> coll)

Returns true if no more elements can be added to the Collection.

This method uses the BoundedCollection interface to determine the full status. If the collection does not implement this interface then false is returned.

The collection does not have to implement this interface directly. If the collection has been decorated using the decorators subpackage then these will be removed to access the BoundedCollection.

Parameters:

coll - the collection to check

Returns:

true if the BoundedCollection is full

Throws:

java.lang.NullPointerException - if the collection is null

maxSize

public static int maxSize(java.util.Collection<? extends java.lang.Object> coll)

Get the maximum number of elements that the Collection can contain.

This method uses the BoundedCollection interface to determine the maximum size. If the collection does not implement this interface then -1 is returned.

The collection does not have to implement this interface directly. If the collection has been decorated using the decorators subpackage then these will be removed to access the BoundedCollection.

Parameters:

coll - the collection to check

Returns:

the maximum size of the BoundedCollection, -1 if no maximum size

Throws:

java.lang.NullPointerException - if the collection is null

collate

public static <O extends java.lang.Comparable<? super O>> java.util.List<O> collate(java.lang.Iterable<? extends O> a,
                                                                                    java.lang.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:

java.lang.NullPointerException - if either collection is null

Since:

4.0

collate

public static <O extends java.lang.Comparable<? super O>> java.util.List<O> collate(java.lang.Iterable<? extends O> a,
                                                                                    java.lang.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 true duplicate 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:

java.lang.NullPointerException - if either collection is null

Since:

4.0

collate

public static <O> java.util.List<O> collate(java.lang.Iterable<? extends O> a,
                                            java.lang.Iterable<? extends O> b,
                                            java.util.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:

java.lang.NullPointerException - if either collection or the comparator is null

Since:

4.0

collate

public static <O> java.util.List<O> collate(java.lang.Iterable<? extends O> a,
                                            java.lang.Iterable<? extends O> b,
                                            java.util.Comparator<? super O> c,
                                            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:

a - the first collection, must not be null

b - the second collection, must not be null

c - the comparator to use for the merge.

includeDuplicates - if true duplicate elements will be retained, otherwise they will be removed in the output collection

Returns:

a new sorted List, containing the elements of Collection a and b

Throws:

java.lang.NullPointerException - if either collection or the comparator is null

Since:

4.0

permutations

public static <E> java.util.Collection<java.util.List<E>> permutations(java.util.Collection<E> collection)

Returns a Collection of all the permutations of the input collection.

NOTE: the number of permutations of a given collection is equal to n!, where n is the size of the collection. Thus, the resulting collection will become very large for collections > 10 (e.g. 10! = 3628800, 15! = 1307674368000).

For larger collections it is advised to use a PermutationIterator to iterate over all permutations.

Type Parameters:

E - the element type

Parameters:

collection - the collection to create permutations for, may not be null

Returns:

an unordered collection of all permutations of the input collection

Throws:

java.lang.NullPointerException - if collection is null

Since:

4.0

See Also:

PermutationIterator

retainAll

public static <C> java.util.Collection<C> retainAll(java.util.Collection<C> collection,
                                                    java.util.Collection<?> retain)

Returns a collection containing all the elements in collection that are also in retain. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless retain does not contain e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call c.retainAll(retain);.

This implementation iterates over collection, checking each element in turn to see if it's contained in retain. If it's contained, it's added to the returned list. As a consequence, it is advised to use a collection type for retain that provides a fast (e.g. O(1)) implementation of Collection.contains(Object).

Type Parameters:

C - the type of object the Collection contains

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 Collection containing all the elements of collection that occur at least once in retain.

Throws:

java.lang.NullPointerException - if either parameter is null

Since:

3.2

retainAll

public static <E> java.util.Collection<E> retainAll(java.lang.Iterable<E> collection,
                                                    java.lang.Iterable<? extends E> retain,
                                                    Equator<? super E> equator)

Returns a collection containing all the elements in collection that are also in retain. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless retain does not contain e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call c.retainAll(retain);.

Moreover this method uses an Equator instead of Object.equals(Object) to determine the equality of the elements in collection and retain. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.

Type Parameters:

E - the type of object the Collection contains

Parameters:

collection - the collection whose contents are the target of the retainAll operation

retain - the collection containing the elements to be retained in the returned collection

equator - the Equator used for testing equality

Returns:

a Collection containing all the elements of collection that occur at least once in retain according to the equator

Throws:

java.lang.NullPointerException - if any of the parameters is null

Since:

4.1

removeAll

public static <E> java.util.Collection<E> removeAll(java.util.Collection<E> collection,
                                                    java.util.Collection<?> remove)

Removes the elements in remove from collection. That is, this method returns a collection containing all the elements in c that are not in remove. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless remove contains e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call collection.removeAll(remove);.

This implementation iterates over collection, checking each element in turn to see if it's contained in remove. If it's not contained, it's added to the returned list. As a consequence, it is advised to use a collection type for remove that provides a fast (e.g. O(1)) implementation of Collection.contains(Object).

Type Parameters:

E - the type of object the Collection contains

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 Collection containing all the elements of collection except any elements that also occur in remove.

Throws:

java.lang.NullPointerException - if either parameter is null

Since:

4.0 (method existed in 3.2 but was completely broken)

removeAll

public static <E> java.util.Collection<E> removeAll(java.lang.Iterable<E> collection,
                                                    java.lang.Iterable<? extends E> remove,
                                                    Equator<? super E> equator)

Removes all elements in remove from collection. That is, this method returns a collection containing all the elements in collection that are not in remove. The cardinality of an element e in the returned collection is the same as the cardinality of e in collection unless remove contains e, in which case the cardinality is zero. This method is useful if you do not wish to modify the collection c and thus cannot call collection.removeAll(remove).

Moreover this method uses an Equator instead of Object.equals(Object) to determine the equality of the elements in collection and remove. Hence this method is useful in cases where the equals behavior of an object needs to be modified without changing the object itself.

Type Parameters:

E - the type of object the Collection contains

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 Collection containing all the elements of collection except any element that if equal according to the equator

Throws:

java.lang.NullPointerException - if any of the parameters is null

Since:

4.1

synchronizedCollection

@Deprecated
public static <C> java.util.Collection<C> synchronizedCollection(java.util.Collection<C> collection)

Deprecated. since 4.1, use Collections.synchronizedCollection(Collection) instead

Returns a synchronized collection backed by the given collection.

You must manually synchronize on the returned buffer's iterator to avoid non-deterministic behavior:

 Collection c = CollectionUtils.synchronizedCollection(myCollection);
 synchronized (c) {
     Iterator i = c.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 

This method uses the implementation in the decorators subpackage.

Type Parameters:

C - the type of object the Collection contains

Parameters:

collection - the collection to synchronize, must not be null

Returns:

a synchronized collection backed by the given collection

Throws:

java.lang.NullPointerException - if the collection is null

unmodifiableCollection

@Deprecated
public static <C> java.util.Collection<C> unmodifiableCollection(java.util.Collection<? extends C> collection)

Deprecated. since 4.1, use Collections.unmodifiableCollection(Collection) instead

Returns 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 Collection contains

Parameters:

collection - the collection to make unmodifiable, must not be null

Returns:

an unmodifiable collection backed by the given collection

Throws:

java.lang.NullPointerException - if the collection is null

predicatedCollection

public static <C> java.util.Collection<C> predicatedCollection(java.util.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:

java.lang.NullPointerException - if the Collection is null

transformingCollection

public static <E> java.util.Collection<E> transformingCollection(java.util.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 behaviour, see TransformedCollection.transformedCollection(java.util.Collection<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>).

Type Parameters:

E - the type of object the Collection contains

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:

java.lang.NullPointerException - if the Collection or Transformer is null

extractSingleton

public static <E> E extractSingleton(java.util.Collection<E> collection)

Extract the lone element of the specified Collection.

Type Parameters:

E - collection type

Parameters:

collection - to read

Returns:

sole member of collection

Throws:

java.lang.NullPointerException - if collection is null

java.lang.IllegalArgumentException - if collection is empty or contains more than one element

Since:

4.0