Apache Commons Collections 4.4 · org.apache.commons.collections4.CollectionUtils

Modifier and Type	Class and Description
private static class	CollectionUtils.CardinalityHelper< the element type O> Helper class to easily access cardinality properties of two collections.
private static class	CollectionUtils.EquatorWrapper< the element type O> Wraps another object and uses the provided Equator to implement `equals(Object)` and `hashCode()`.
private static class	CollectionUtils.SetOperationCardinalityHelper< the element type O> Helper class for set-related operations, e.g. union, subtract, intersection.

Modifier and Type	Field and Description
public static final Collection<E>	EMPTY_COLLECTION An empty unmodifiable collection.

Access	Constructor and Description
private	CollectionUtils() `CollectionUtils` should not normally be instantiated.

Method Summary

Modifier and Type	Method and Description
public static < the type of object the `Collection` contains C> boolean	Returns: a boolean indicating whether the collection has changed or not. addAll(final Collection<C> the collection to add to, must not be null collection, final Iterable<? extends C> the iterable of elements to add, must not be null iterable) Adds all elements in the `Iterable` to the given collection.
public static < the type of object the `Collection` contains C> boolean	Returns: a boolean indicating whether the collection has changed or not. addAll(final Collection<C> the collection to add to, must not be null collection, final Iterator<? extends C> the iterator of elements to add, must not be null iterator) Adds all elements in the iteration to the given collection.
public static < the type of object the `Collection` contains C> boolean	Returns: `true` if the collections was changed, `false` otherwise addAll(final Collection<C> the collection to add to, must not be null collection, final Enumeration<? extends C> the enumeration of elements to add, must not be null enumeration) Adds all elements in the enumeration to the given collection.
public static < the type of object the `Collection` contains C> boolean	Returns: `true` if the collection was changed, `false` otherwise addAll(final Collection<C> the collection to add to, must not be null collection, final C... the array of elements to add, must not be null elements) Adds all elements in the array to the given collection.
public static < the type of object the `Collection` contains T> boolean	Returns: true if the collection changed addIgnoreNull(final Collection<T> the collection to add to, must not be null collection, final T the object to add, if null it will not be added object) Adds an element to the collection unless the element is null.
public static < the type of object that the `Iterable` may contain. O> int	Returns: the number of occurrences of obj in coll cardinality(final O the object to find the cardinality of obj, final Iterable<? super O> the `Iterable` to search coll) Deprecated since 4.1, use `IterableUtils#frequency(Iterable, Object)` instead. Returns the number of occurrences of obj in coll.
pack-priv static void	checkIndexBounds(final int the index to check. index) Ensures an index is not negative.
public static < the element type O extends Comparable<? super O>> List<O>	Returns: a new sorted List, containing the elements of Collection a and b collate(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b) Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
public static < the element type O extends Comparable<? super O>> List<O>	Returns: a new sorted List, containing the elements of Collection a and b collate(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b, final boolean if `true` duplicate elements will be retained, otherwise they will be removed in the output collection includeDuplicates) Merges two sorted Collections, a and b, into a single, sorted List such that the natural ordering of the elements is retained.
public static < the element type O> List<O>	Returns: a new sorted List, containing the elements of Collection a and b collate(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b, final Comparator<? super O> the comparator to use for the merge. 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.
public static < the element type O> List<O>	Returns: a new sorted List, containing the elements of Collection a and b collate(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b, final Comparator<? super O> the comparator to use for the merge. c, final boolean if `true` duplicate elements will be retained, otherwise they will be removed in the output collection 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.
public static < the type of object in the input collection I, the type of object in the output collection O> Collection<O>	Returns: the transformed result (new list) collect(final Iterable<I> the collection to get the input from, may not be null inputCollection, final Transformer<? super I, ? extends O> the transformer to use, may be null transformer) Returns a new Collection containing all elements of the input collection transformed by the given transformer.
public static < the type of object in the input collection I, the type of object in the output collection O> Collection<O>	Returns: the transformed result (new list) collect(final Iterator<I> the iterator to get the input from, may be null inputIterator, final Transformer<? super I, ? extends O> the transformer to use, may be null transformer) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.
public static < the type of object in the input collection I, the type of object in the output collection O, the type of the output collection R extends Collection<? super O>> R	Returns: the output collection with the transformed input added collect(final Iterable<? extends I> the collection to get the input from, may be null inputCollection, final Transformer<? super I, ? extends O> the transformer to use, may be null transformer, final R the collection to output into, may not be null if inputCollection and transformer are not null outputCollection) Transforms all elements from input collection with the given transformer and adds them to the output collection.
public static < the type of object in the input collection I, the type of object in the output collection O, the type of the output collection R extends Collection<? super O>> R	Returns: the outputCollection with the transformed input added collect(final Iterator<? extends I> the iterator to get the input from, may be null inputIterator, final Transformer<? super I, ? extends O> the transformer to use, may be null transformer, final R the collection to output into, may not be null if inputIterator and transformer are not null outputCollection) Transforms all elements from the input iterator with the given transformer and adds them to the output collection.
public static boolean	Returns: `true` iff the intersection of the collections has the same cardinality as the set of unique elements from the second collection containsAll(final Collection<?> the first collection, must not be null coll1, final Collection<?> the second collection, must not be null coll2) Returns `true` iff all elements of `coll2` are also contained in `coll1`.
public static < the type of object to lookup in `coll1`. T> boolean	Returns: `true` iff the intersection of the collections is non-empty containsAny(final Collection<?> the first collection, must not be null coll1, final T... the second collection, must not be null coll2) Returns `true` iff at least one element is in both collections.
public static boolean	Returns: `true` iff the intersection of the collections is non-empty containsAny(final Collection<?> the first collection, must not be null coll1, final Collection<?> the second collection, must not be null coll2) Returns `true` iff at least one element is in both collections.
public static < the type of object the `Iterable` contains C> int	Returns: the number of matches for the predicate in the collection countMatches(final Iterable<C> the `Iterable` to get the input from, may be null input, final Predicate<? super C> the predicate to use, may be null predicate) Deprecated since 4.1, use `IterableUtils#countMatches(Iterable, Predicate)` instead Counts the number of elements in the input collection that match the predicate.
public static < the generic type that is able to represent the types contained in both input collections. O> Collection<O>	Returns: the symmetric difference of the two collections disjunction(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b) Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Iterable`s.
public static < the element type T> Collection<T>	Returns: immutable empty collection emptyCollection() Returns the immutable EMPTY_COLLECTION with generic type safety.
public static < the element type T> Collection<T>	Returns: an empty collection if the argument is `null` emptyIfNull(final Collection<T> the collection, possibly `null` collection) Returns an immutable empty collection if the argument is `null`, or the argument itself otherwise.
public static < the type of object the `Iterable` contains C> boolean	Returns: true if at least one element of the collection matches the predicate exists(final Iterable<C> the `Iterable` to get the input from, may be null input, final Predicate<? super C> the predicate to use, may be null 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.
public static < collection type E> E	Returns: sole member of collection extractSingleton(final Collection<E> to read collection) Extract the lone element of the specified Collection.
public static < the type of object the `Iterable` contains T> boolean	Returns: true if the collection is modified by this call, false otherwise. filter(final Iterable<T> the collection to get the input from, may be null collection, final Predicate<? super T> the predicate to use as a filter, may be null predicate) Filter the collection by applying a Predicate to each element.
public static < the type of object the `Iterable` contains T> boolean	Returns: true if the collection is modified by this call, false otherwise. filterInverse(final Iterable<T> the collection to get the input from, may be null collection, final Predicate<? super T> the predicate to use as a filter, may be null predicate) Filter the collection by applying a Predicate to each element.
public static < the type of object the `Iterable` contains T> T	Returns: the first element of the collection which matches the predicate or null if none could be found find(final Iterable<T> the collection to search, may be null collection, final Predicate<? super T> the predicate to use, may be null predicate) Deprecated since 4.1, use `IterableUtils#find(Iterable, Predicate)` instead Finds the first element in the given collection which matches the given predicate.
public static < the type of object the `Iterable` contains T, the closure type C extends Closure<? super T>> T	Returns: the last element in the collection, or null if either collection or closure is null forAllButLastDo(final Iterable<T> the collection to get the input from, may be null collection, final C the closure to perform, may be null closure) Deprecated since 4.1, use `IterableUtils#forEachButLast(Iterable, Closure)` instead Executes the given closure on each but the last element in the collection.
public static < the type of object the `Collection` contains T, the closure type C extends Closure<? super T>> T	Returns: the last element in the collection, or null if either iterator or closure is null forAllButLastDo(final Iterator<T> the iterator to get the input from, may be null iterator, final C the closure to perform, may be null closure) Deprecated since 4.1, use `IteratorUtils#forEachButLast(Iterator, Closure)` instead Executes the given closure on each but the last element in the collection.
public static < the type of object the `Iterable` contains T, the closure type C extends Closure<? super T>> C	Returns: closure forAllDo(final Iterable<T> the collection to get the input from, may be null collection, final C the closure to perform, may be null closure) Deprecated since 4.1, use `IterableUtils#forEach(Iterable, Closure)` instead Executes the given closure on each element in the collection.
public static < the type of object the `Iterator` contains T, the closure type C extends Closure<? super T>> C	Returns: closure forAllDo(final Iterator<T> the iterator to get the input from, may be null iterator, final C the closure to perform, may be null closure) Deprecated since 4.1, use `IteratorUtils#forEach(Iterator, Closure)` instead Executes the given closure on each element in the collection.
public static < the type of object in the `Iterator` T> T	Returns: the object at the specified index get(final Iterator<T> the iterator to get a value from iterator, final int the index to get 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.
public static < the type of object in the `Iterable`. T> T	Returns: the object at the specified index get(final Iterable<T> the `Iterable` to get a value from iterable, final int the index to get 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.
public static Object	Returns: the object at the specified index get(final Object the object to get a value from object, final int the index to get 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.
public static < the key type in the `Map` K, the key type in the `Map` V> Map.Entry<K, V>	Returns: the object at the specified index get(final Map<K, V> the object to get a value from map, final int the index to get index) Returns the `index`-th `Map.Entry` in the `map`'s `entrySet`, throwing `IndexOutOfBoundsException` if there is no such element.
public static < the type of object in the returned `Map`. This is a super type of <I>. O> Map<O, Integer>	Returns: the populated cardinality map getCardinalityMap(final Iterable<? extends O> the collection to get the cardinality map for, must not be null 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`.
public static < the generic type that is able to represent the types contained in both input collections. O> Collection<O>	Returns: the intersection of the two collections intersection(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b) Returns a `Collection` containing the intersection of the given `Iterable`s.
public static boolean	Returns: true if empty or null isEmpty(final Collection<?> the collection to check, may be null coll) Null-safe check if the specified collection is empty.
public static boolean	Returns: `true` iff the collections contain the same elements with the same cardinalities. isEqualCollection(final Collection<?> the first collection, must not be null a, final Collection<?> the second collection, must not be null b) Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinalities.
public static < the element type E> boolean	Returns: `true` iff the collections contain the same elements with the same cardinalities. isEqualCollection(final Collection<? extends E> the first collection, must not be null a, final Collection<? extends E> the second collection, must not be null b, final Equator<? super E> the Equator used for testing equality equator) Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinalities.
public static boolean	Returns: true if the BoundedCollection is full isFull(final Collection<? extends Object> the collection to check coll) Returns true if no more elements can be added to the Collection.
public static boolean	Returns: true if non-null and non-empty isNotEmpty(final Collection<?> the collection to check, may be null coll) Null-safe check if the specified collection is not empty.
public static boolean	Returns: `true` iff a is a proper sub-collection of b isProperSubCollection(final Collection<?> the first (sub?) collection, must not be null a, final Collection<?> the second (super?) collection, must not be null 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.
public static boolean	Returns: `true` iff a is a sub-collection of b isSubCollection(final Collection<?> the first (sub?) collection, must not be null a, final Collection<?> the second (super?) collection, must not be null 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.
public static < the type of object the `Iterable` contains C> boolean	Returns: true if every element of the collection matches the predicate or if the collection is empty, false otherwise matchesAll(final Iterable<C> the `Iterable` to get the input from, may be null input, final Predicate<? super C> the predicate to use, may be null predicate) Deprecated since 4.1, use `IterableUtils#matchesAll(Iterable, Predicate)` instead Answers true if a predicate is true for every element of a collection.
public static int	Returns: the maximum size of the BoundedCollection, -1 if no maximum size maxSize(final Collection<? extends Object> the collection to check coll) Get the maximum number of elements that the Collection can contain.
public static < the element type E> Collection<List<E>>	Returns: an unordered collection of all permutations of the input collection permutations(final Collection<E> the collection to create permutations for, may not be null collection) Returns a `Collection` of all the permutations of the input collection.
public static < the type of objects in the Collection. C> Collection<C>	Returns: a predicated collection backed by the given collection predicatedCollection(final Collection<C> the collection to predicate, must not be null collection, final Predicate<? super C> the predicate for the collection, must not be null predicate) Returns a predicated (validating) collection backed by the given collection.
public static < the type of object the `Collection` contains E> Collection<E>	Returns: a `Collection` containing all the elements of `collection` except any elements that also occur in `remove`. removeAll(final Collection<E> the collection from which items are removed (in the returned collection) collection, final Collection<?> the items to be removed from the returned `collection` remove) Removes the elements in `remove` from `collection`.
public static < the type of object the `Collection` contains E> Collection<E>	Returns: a `Collection` containing all the elements of `collection` except any element that if equal according to the `equator` removeAll(final Iterable<E> the collection from which items are removed (in the returned collection) collection, final Iterable<? extends E> the items to be removed from the returned collection remove, final Equator<? super E> the Equator used for testing equality equator) Removes all elements in `remove` from `collection`.
public static < the type of object the `Collection` contains C> Collection<C>	Returns: a `Collection` containing all the elements of `collection` that occur at least once in `retain`. retainAll(final Collection<C> the collection whose contents are the target of the #retailAll operation collection, final Collection<?> the collection containing the elements to be retained in the returned collection retain) Returns a collection containing all the elements in `collection` that are also in `retain`.
public static < the type of object the `Collection` contains E> Collection<E>	Returns: a `Collection` containing all the elements of `collection` that occur at least once in `retain` according to the `equator` retainAll(final Iterable<E> the collection whose contents are the target of the `retainAll` operation collection, final Iterable<? extends E> the collection containing the elements to be retained in the returned collection retain, final Equator<? super E> the Equator used for testing equality equator) Returns a collection containing all the elements in `collection` that are also in `retain`.
public static void	reverseArray(final Object[] the array to reverse array) Reverses the order of the given array.
public static < the type of object the `Iterable` contains O> Collection<O>	Returns: the elements matching the predicate (new list) select(final Iterable<? extends O> the collection to get the input from, may not be null inputCollection, final Predicate<? super O> the predicate to use, may be null predicate) Selects all elements from input collection which match the given predicate into an output collection.
public static < the type of object the `Iterable` contains O, the type of the output `Collection` R extends Collection<? super O>> R	Returns: the outputCollection select(final Iterable<? extends O> the collection to get the input from, may be null inputCollection, final Predicate<? super O> the predicate to use, may be null predicate, final R the collection to output into, may not be null if the inputCollection and predicate or not null outputCollection) Selects all elements from input collection which match the given predicate and adds them to outputCollection.
public static < the type of object the `Iterable` contains O, the type of the output `Collection` R extends Collection<? super O>> R	Returns: the outputCollection select(final Iterable<? extends O> the collection to get the input from, may be null inputCollection, final Predicate<? super O> the predicate to use, may be null predicate, final R the collection to output selected elements into, may not be null if the inputCollection and predicate are not null outputCollection, final R the collection to output rejected elements into, may not be null if the inputCollection or predicate are not null rejectedCollection) Selects all elements from inputCollection into an output and rejected collection, based on the evaluation of the given predicate.
public static < the type of object the `Iterable` contains O> Collection<O>	Returns: the elements not matching the predicate (new list) selectRejected(final Iterable<? extends O> the collection to get the input from, may not be null inputCollection, final Predicate<? super O> the predicate to use, may be null predicate) Selects all elements from inputCollection which don't match the given predicate into an output collection.
public static < the type of object the `Iterable` contains O, the type of the output `Collection` R extends Collection<? super O>> R	Returns: outputCollection selectRejected(final Iterable<? extends O> the collection to get the input from, may be null inputCollection, final Predicate<? super O> the predicate to use, may be null predicate, final R the collection to output into, may not be null if the inputCollection and predicate or not null outputCollection) Selects all elements from inputCollection which don't match the given predicate and adds them to outputCollection.
public static int	Returns: the size of the specified collection or 0 if the object was null size(final Object the object to get the size of, may be null object) Gets the size of the collection/iterator specified.
public static boolean	Returns: true if empty or null sizeIsEmpty(final Object the object to get the size of, may be null object) Checks if the specified collection/array/iterator is empty.
public static < the generic type that is able to represent the types contained in both input collections. O> Collection<O>	Returns: a new collection with the results subtract(final Iterable<? extends O> the collection to subtract from, must not be null a, final Iterable<? extends O> the collection to subtract, must not be null b) Returns a new `Collection` containing `<i>a</i> - <i>b</i>`.
public static < the generic type that is able to represent the types contained in both input collections. O> Collection<O>	Returns: a new collection with the results subtract(final Iterable<? extends O> the collection to subtract from, must not be null a, final Iterable<? extends O> the collection to subtract, must not be null b, final Predicate<O> the condition used to determine which elements of b are subtracted. p) Returns a new `Collection` containing a minus a subset of b.
public static < the type of object the `Collection` contains C> Collection<C>	Returns: a synchronized collection backed by the given collection synchronizedCollection(final Collection<C> the collection to synchronize, must not be null collection) Deprecated since 4.1, use `java.util.Collections#synchronizedCollection(Collection)` instead Returns a synchronized collection backed by the given collection.
public static < the type of object the `Collection` contains C> void	transform(final Collection<C> the `Collection` to get the input from, may be null collection, final Transformer<? super C, ? extends C> the transformer to perform, may be null transformer) Transform the collection by applying a Transformer to each element.
public static < the type of object the `Collection` contains E> Collection<E>	Returns: a transformed collection backed by the given collection transformingCollection(final Collection<E> the collection to predicate, must not be null collection, final Transformer<? super E, ? extends E> the transformer for the collection, must not be null transformer) Returns a transformed bag backed by the given collection.
public static < the generic type that is able to represent the types contained in both input collections. O> Collection<O>	Returns: the union of the two collections union(final Iterable<? extends O> the first collection, must not be null a, final Iterable<? extends O> the second collection, must not be null b) Returns a `Collection` containing the union of the given `Iterable`s.
public static < the type of object the `Collection` contains C> Collection<C>	Returns: an unmodifiable collection backed by the given collection unmodifiableCollection(final Collection<? extends C> the collection to make unmodifiable, must not be null collection) Deprecated since 4.1, use `java.util.Collections#unmodifiableCollection(Collection)` instead Returns an unmodifiable collection backed by the given collection.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public Class CollectionUtils

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary