CollectionUtils (Jakarta Commons Collections Package)

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.apache.commons.collections
Class CollectionUtils

java.lang.Object
  |
  +--org.apache.commons.collections.CollectionUtils

public class CollectionUtils
extends Object

A set of Collection related utility methods.

Since:: 1.0
Version:: $Revision: 1.18 $ $Date: 2002/10/13 00:38:36 $
Author:: Rodney Waldhoff, Paul Jack, Stephen Colebourne, Steve Downey

Constructor Summary

CollectionUtils()
          Please don't ever instantiate a CollectionUtils.

Method Summary

static void addAll(Collection collection, Enumeration enumeration)
          Adds all elements in the enumeration to the given collection.

static void addAll(Collection collection, Iterator iterator)
          Adds all elements in the iteration to the given collection.

static void addAll(Collection collection, Object[] elements)
          Adds all elements in the array to the given collection.

static int cardinality(Object obj, Collection col)
          Returns the number of occurrences of obj in col.

static Collection collect(Collection inputCollection, Transformer transformer)
          Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.

static Collection collect(Collection inputCollection, Transformer transformer, Collection outputCollection)
          Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.

static Collection collect(Iterator inputIterator, Transformer transformer)
          Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

static Collection collect(Iterator inputIterator, Transformer transformer, Collection outputCollection)
          Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

static boolean containsAny(Collection a, Collection b)
          Returns true iff some element of a is also an element of b (or, equivalently, if some element of b is also an element of a).

static Collection disjunction(Collection a, Collection b)
          Returns a Collection containing the exclusive disjunction (symmetric difference) of the given Collections.

static void filter(Collection collection, Predicate predicate)
          Filter the collection by applying a Predicate to each element.

static Object find(Collection collection, Predicate predicate)
          Finds the first element in the given collection which matches the given predicate.

static void forAllDo(Collection collection, Closure closure)
          Executes the given closure on each element in the collection.

static Map getCardinalityMap(Collection col)
          Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurances of that element in the Collection.

static Object index(Object obj, int idx)
          Given an Object, and an index, it will get the nth value in the object.

static Object index(Object obj, Object index)
          Given an Object, and a key (index), it will get value associated with that key in the Object.

static Collection intersection(Collection a, Collection b)
          Returns a Collection containing the intersection of the given Collections.

static boolean isEqualCollection(Collection a, Collection b)
          Returns true iff the given Collections contain exactly the same elements with exactly the same cardinality.

static boolean isProperSubCollection(Collection a, 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(Collection a, 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 Collection predicatedCollection(Collection collection, Predicate predicate)
          Returns a predicated collection backed by the given collection.

static void reverseArray(Object[] array)
          Reverses the order of the given array

static Collection select(Collection inputCollection, Predicate predicate)
          Selects all elements from input collection which match the given predicate into an output collection.

static void select(Collection inputCollection, Predicate predicate, Collection outputCollection)
          Selects all elements from input collection which match the given predicate and adds them to outputCollection.

static Collection subtract(Collection a, Collection b)
          Returns a Collection containing a - b.

static void transform(Collection collection, Transformer transformer)
          Transform the collection by applying a Transformer to each element.

static Collection union(Collection a, Collection b)
          Returns a Collection containing the union of the given Collections.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionUtils

public CollectionUtils()

Please don't ever instantiate a CollectionUtils.

Method Detail

addAll

public static void addAll(Collection collection,
                          Enumeration enumeration)

Adds all elements in the enumeration to the given collection.

Parameters:: collection - the collection to add to; enumeration - the enumeration of elements to add, may not be null
Throws:: NullPointerException - if the collection or enumeration is null

addAll

public static void addAll(Collection collection,
                          Iterator iterator)

Adds all elements in the iteration to the given collection.

Parameters:: collection - the collection to add to; iterator - the iterator of elements to add, may not be null
Throws:: NullPointerException - if the collection or iterator is null

addAll

public static void addAll(Collection collection,
                          Object[] elements)

Adds all elements in the array to the given collection.

Parameters:: collection - the collection to add to; elements - the array of elements to add, may be null
Throws:: NullPointerException - if the collection or array is null

cardinality

public static int cardinality(Object obj,
                              Collection col)

Returns the number of occurrences of obj in col.

collect

public static Collection collect(Collection inputCollection,
                                 Transformer transformer)

Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.

If the input transfomer is null, the result is an empty list.

Parameters:: inputCollection - the collection to get the input from, may not be null; transformer - the transformer to use, may be null
Returns:: the transformed result (new list)
Throws:: NullPointerException - if the input collection is null

collect

public static Collection collect(Collection inputCollection,
                                 Transformer transformer,
                                 Collection outputCollection)

Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.

If the input collection or transfomer is null, there is no change to 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
Returns:: the outputCollection with the transformed input added
Throws:: NullPointerException - if the output collection is null

collect

public static Collection collect(Iterator inputIterator,
                                 Transformer transformer)

Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

If the input iterator or transfomer is null, the result is an empty list.

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 Collection collect(Iterator inputIterator,
                                 Transformer transformer,
                                 Collection outputCollection)

Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.

If the input iterator or transfomer is null, there is no change to 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
Returns:: the outputCollection with the transformed input added
Throws:: NullPointerException - if the output collection is null

containsAny

public static boolean containsAny(Collection a,
                                  Collection b)

Returns true iff some element of a is also an element of b (or, equivalently, if some element of b is also an element of a). In other words, this method returns true iff the intersection(java.util.Collection, java.util.Collection) of a and b is not empty.

Parameters:: a - a non-null Collection; b - a non-null Collection
Returns:: true iff the intersection of a and b is non-empty
Since:: 2.1
See Also:: intersection(java.util.Collection, java.util.Collection)

disjunction

public static Collection disjunction(Collection a,
                                     Collection b)

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

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 subtract(union(a,b),intersection(a,b)) or union(subtract(a,b),subtract(b,a)).

filter

public static void filter(Collection collection,
                          Predicate 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.

Parameters:: collection - the collection to get the input from, may be null; predicate - the predicate to use as a filter, may be null

find

public static Object find(Collection collection,
                          Predicate predicate)

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

If the input collection or predicate is null, null is returned.

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

public static void forAllDo(Collection collection,
                            Closure closure)

Executes the given closure on each element in the collection.

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

Parameters:: collection - the collection to get the input from, may be null; closure - the closure to perform, may not be null
Throws:: NullPointerException - if the closure is null

getCardinalityMap

public static Map getCardinalityMap(Collection col)

Returns a Map mapping each unique element in the given Collection to an Integer representing the number of occurances of that element in the Collection. An entry that maps to null indicates that the element does not appear in the given Collection.

index

public static Object index(Object obj,
                           int idx)

Given an Object, and an index, it will get the nth value in the object.

If obj is a Map, get the nth value from the key iterator.
If obj is a List or an array, get the nth value.
If obj is an iterator, enumeration or Collection, get the nth value from the iterator.
Return the original obj.

Parameters:: obj - the object to get an index of
Throws:: IndexOutOfBoundsException; NoSuchElementException

index

public static Object index(Object obj,
                           Object index)

Given an Object, and a key (index), it will get value associated with that key in the Object. The following checks are made:

If obj is a Map, use the index as a key to get a value. If no match continue.
Check key is an Integer. If not, return the object passed in.
If obj is a Map, get the nth value from the key iterator.
If obj is a List or an array, get the nth value.
If obj is an iterator, enumeration or Collection, get the nth value from the iterator.
Return the original obj.

Parameters:: obj - the object to get an index of; index - the index to get
Returns:: the object at the specified index
Throws:: IndexOutOfBoundsException; NoSuchElementException

intersection

public static Collection intersection(Collection a,
                                      Collection b)

Returns a Collection containing the intersection of the given Collections.

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 Collections.

See Also:: Collection.retainAll(java.util.Collection), containsAny(java.util.Collection, java.util.Collection)

isEqualCollection

public static boolean isEqualCollection(Collection a,
                                        Collection b)

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

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.

isProperSubCollection

public static boolean isProperSubCollection(Collection a,
                                            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.

See Also:: isSubCollection(java.util.Collection, java.util.Collection), Collection.containsAll(java.util.Collection)

isSubCollection

public static boolean isSubCollection(Collection a,
                                      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.

See Also:: isProperSubCollection(java.util.Collection, java.util.Collection), Collection.containsAll(java.util.Collection)

predicatedCollection

public static Collection predicatedCollection(Collection collection,
                                              Predicate predicate)

Returns a predicated collection backed by the given collection. Only objects that pass the test in the given predicate can be added to the collection. It is important not to use the original collection after invoking this method, as it is a backdoor for adding unvalidated objects.

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:: IllegalArgumentException - if the Collection is null

reverseArray

public static void reverseArray(Object[] array)

Reverses the order of the given array

select

public static Collection select(Collection inputCollection,
                                Predicate predicate)

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

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:: NullPointerException - if the input collection is null

select

public static void select(Collection inputCollection,
                          Predicate predicate,
                          Collection 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.

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
Returns:: the outputCollection with the the elements matching the predicate added
Throws:: NullPointerException - if the input collection is null

subtract

public static Collection subtract(Collection a,
                                  Collection b)

Returns a Collection containing a - b. 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.

See Also:: Collection.removeAll(java.util.Collection)

transform

public static void transform(Collection collection,
                             Transformer 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 and uses set(), however it adapts for all Collections that support clear() and addAll().

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.

Parameters:: collection - the collection to get the input from, may be null; transformer - the transformer to perform, may be null

union

public static Collection union(Collection a,
                               Collection b)

Returns a Collection containing the union of the given Collections.

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 Collections.

See Also:: Collection.addAll(java.util.Collection)

Overview

Package

Class

Index

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Constructor Summary
`CollectionUtils()` Please don't ever instantiate a `CollectionUtils`.

Method Summary
`static void`	`addAll(Collection collection, Enumeration enumeration)` Adds all elements in the enumeration to the given collection.
`static void`	`addAll(Collection collection, Iterator iterator)` Adds all elements in the iteration to the given collection.
`static void`	`addAll(Collection collection, Object[] elements)` Adds all elements in the array to the given collection.
`static int`	`cardinality(Object obj, Collection col)` Returns the number of occurrences of obj in col.
`static Collection`	`collect(Collection inputCollection, Transformer transformer)` Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.
`static Collection`	`collect(Collection inputCollection, Transformer transformer, Collection outputCollection)` Transforms all elements from inputCollection with the given transformer and adds them to the outputCollection.
`static Collection`	`collect(Iterator inputIterator, Transformer transformer)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
`static Collection`	`collect(Iterator inputIterator, Transformer transformer, Collection outputCollection)` Transforms all elements from the inputIterator with the given transformer and adds them to the outputCollection.
`static boolean`	`containsAny(Collection a, Collection b)` Returns `true` iff some element of a is also an element of b (or, equivalently, if some element of b is also an element of a).
`static Collection`	`disjunction(Collection a, Collection b)` Returns a `Collection` containing the exclusive disjunction (symmetric difference) of the given `Collection`s.
`static void`	`filter(Collection collection, Predicate predicate)` Filter the collection by applying a Predicate to each element.
`static Object`	`find(Collection collection, Predicate predicate)` Finds the first element in the given collection which matches the given predicate.
`static void`	`forAllDo(Collection collection, Closure closure)` Executes the given closure on each element in the collection.
`static Map`	`getCardinalityMap(Collection col)` Returns a `Map` mapping each unique element in the given `Collection` to an `Integer` representing the number of occurances of that element in the `Collection`.
`static Object`	`index(Object obj, int idx)` Given an Object, and an index, it will get the nth value in the object.
`static Object`	`index(Object obj, Object index)` Given an Object, and a key (index), it will get value associated with that key in the Object.
`static Collection`	`intersection(Collection a, Collection b)` Returns a `Collection` containing the intersection of the given `Collection`s.
`static boolean`	`isEqualCollection(Collection a, Collection b)` Returns `true` iff the given `Collection`s contain exactly the same elements with exactly the same cardinality.
`static boolean`	`isProperSubCollection(Collection a, 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(Collection a, 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 Collection`	`predicatedCollection(Collection collection, Predicate predicate)` Returns a predicated collection backed by the given collection.
`static void`	`reverseArray(Object[] array)` Reverses the order of the given array
`static Collection`	`select(Collection inputCollection, Predicate predicate)` Selects all elements from input collection which match the given predicate into an output collection.
`static void`	`select(Collection inputCollection, Predicate predicate, Collection outputCollection)` Selects all elements from input collection which match the given predicate and adds them to outputCollection.
`static Collection`	`subtract(Collection a, Collection b)` Returns a `Collection` containing `a - b`.
`static void`	`transform(Collection collection, Transformer transformer)` Transform the collection by applying a Transformer to each element.
`static Collection`	`union(Collection a, Collection b)` Returns a `Collection` containing the union of the given `Collection`s.

org.apache.commons.collections Class CollectionUtils

CollectionUtils

addAll

addAll

addAll

cardinality

collect

collect

collect

collect

containsAny

disjunction

filter

find

forAllDo

getCardinalityMap

index

index

intersection

isEqualCollection

isProperSubCollection

isSubCollection

predicatedCollection

reverseArray

select

select

subtract

transform

union

org.apache.commons.collections
Class CollectionUtils