org.apache.commons.collections
Class ListUtils

java.lang.Object
  org.apache.commons.collections.ListUtils

public class ListUtils
extends Object

Provides utility methods and decorators for List instances.

Since:

Commons Collections 1.0

Version:

$Revision: 1.2 $ $Date: 2005/05/23 14:42:13 $

Author:

Federico Barbieri, Peter Donald, Paul Jack, Stephen Colebourne, Neil O'Toole, Matt Hall, John Watkinson, Matthew Hawthorne

Field Summary

static List

EMPTY_LIST An empty unmodifiable list.

Constructor Summary

ListUtils()
ListUtils should not normally be instantiated.

Method Summary

static <E> List<E>	fixedSizeList(List<E> list) Returns a fixed-sized list backed by the given list.
static int	hashCodeForList(Collection list) Generates a hash code using the algorithm specified in List.hashCode().
static <E> List<E>	intersection(List<? extends E> list1, List<? extends E> list2) Returns a new list containing all elements that are contained in both given lists.
static <E> boolean	isEqualList(Collection<? extends E> list1, Collection<? extends E> list2) Tests two lists for value-equality as per the equality contract in List.equals(java.lang.Object).
static <E> List<E>	lazyList(List<E> list, Factory<? extends E> factory) Returns a "lazy" list whose elements will be created on demand.
static <E> List<E>	predicatedList(List<E> list, Predicate<? super E> predicate) Returns a predicated (validating) list backed by the given list.
static <E> List<E>	subtract(List<? extends E> list1, List<? extends E> list2) Subtracts all elements in the second list from the first list, placing the results in a new list.
static <E> List<E>	sum(List<? extends E> list1, List<? extends E> list2) Returns the sum of the given lists.
static <E> List<E>	synchronizedList(List<E> list) Returns a synchronized list backed by the given list.
static <I,O> List<O>	transformedList(List<I> list, Transformer<? super I,? extends O> transformer) Returns a transformed list backed by the given list.
static <E> List<E>	typedList(List<E> list, Class<E> type) Deprecated. Java generics makes this method obsolete.
static <E> List<E>	union(List<? extends E> list1, List<? extends E> list2) Returns a new list containing the second list appended to the first list.
static <E> List<E>	unmodifiableList(List<E> list) Returns an unmodifiable list backed by the given list.

Methods inherited from class java.lang.Object

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

Field Detail

EMPTY_LIST

public static final List EMPTY_LIST

An empty unmodifiable list. This uses the Collections implementation and is provided for completeness.

Constructor Detail

ListUtils

public ListUtils()

ListUtils should not normally be instantiated.

Method Detail

intersection

public static <E> List<E> intersection(List<? extends E> list1,
                                       List<? extends E> list2)

Returns a new list containing all elements that are contained in both given lists.

Parameters:

list1 - the first list

list2 - the second list

Returns:

the intersection of those two lists

Throws:

NullPointerException - if either list is null

subtract

public static <E> List<E> subtract(List<? extends E> list1,
                                   List<? extends E> list2)

Subtracts all elements in the second list from the first list, placing the results in a new list.

This differs from List.removeAll(Collection) in that cardinality is respected; if list1 contains two occurrences of null and list2 only contains one occurrence, then the returned list will still contain one occurrence.

Parameters:

list1 - the list to subtract from

list2 - the list to subtract

Returns:

a new list containing the results

Throws:

NullPointerException - if either list is null

sum

public static <E> List<E> sum(List<? extends E> list1,
                              List<? extends E> list2)

Returns the sum of the given lists. This is their intersection subtracted from their union.

Parameters:

list1 - the first list

list2 - the second list

Returns:

a new list containing the sum of those lists

Throws:

NullPointerException - if either list is null

union

public static <E> List<E> union(List<? extends E> list1,
                                List<? extends E> list2)

Returns a new list containing the second list appended to the first list. The List.addAll(Collection) operation is used to append the two given lists into a new list.

Parameters:

list1 - the first list

list2 - the second list

Returns:

a new list containing the union of those lists

Throws:

NullPointerException - if either list is null

isEqualList

public static <E> boolean isEqualList(Collection<? extends E> list1,
                                      Collection<? extends E> list2)

Tests two lists for value-equality as per the equality contract in List.equals(java.lang.Object).

This method is useful for implementing List when you cannot extend AbstractList. The method takes Collection instances to enable other collection types to use the List implementation algorithm.

The relevant text (slightly paraphrased as this is a static method) is:

Compares the two list objects for equality. Returns true if and only if both lists have the same size, and all corresponding pairs of elements in the two lists are equal. (Two elements e1 and e2 are equal if (e1==null ? e2==null : e1.equals(e2)).) In other words, two lists are defined to be equal if they contain the same elements in the same order. This definition ensures that the equals method works properly across different implementations of the List interface.

Note: The behaviour of this method is undefined if the lists are modified during the equals comparison.

Parameters:

list1 - the first list, may be null

list2 - the second list, may be null

Returns:

whether the lists are equal by value comparison

See Also:

List

hashCodeForList

public static int hashCodeForList(Collection list)

Generates a hash code using the algorithm specified in List.hashCode().

This method is useful for implementing List when you cannot extend AbstractList. The method takes Collection instances to enable other collection types to use the List implementation algorithm.

Parameters:

list - the list to generate the hashCode for, may be null

Returns:

the hash code

See Also:

List.hashCode()

synchronizedList

public static <E> List<E> synchronizedList(List<E> list)

Returns a synchronized list backed by the given list.

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

 List list = ListUtils.synchronizedList(myList);
 synchronized (list) {
     Iterator i = list.iterator();
     while (i.hasNext()) {
         process (i.next());
     }
 }
 

This method uses the implementation in the decorators subpackage.

Parameters:

list - the list to synchronize, must not be null

Returns:

a synchronized list backed by the given list

Throws:

IllegalArgumentException - if the list is null

unmodifiableList

public static <E> List<E> unmodifiableList(List<E> list)

Returns an unmodifiable list backed by the given list.

This method uses the implementation in the decorators subpackage.

Parameters:

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

Returns:

an unmodifiable list backed by the given list

Throws:

IllegalArgumentException - if the list is null

predicatedList

public static <E> List<E> predicatedList(List<E> list,
                                         Predicate<? super E> predicate)

Returns a predicated (validating) list backed by the given list.

Only objects that pass the test in the given predicate can be added to the list. Trying to add an invalid object results in an IllegalArgumentException. It is important not to use the original list after invoking this method, as it is a backdoor for adding invalid objects.

Parameters:

list - the list to predicate, must not be null

predicate - the predicate for the list, must not be null

Returns:

a predicated list backed by the given list

Throws:

IllegalArgumentException - if the List or Predicate is null

typedList

public static <E> List<E> typedList(List<E> list,
                                    Class<E> type)

Deprecated. Java generics makes this method obsolete.

Returns a typed list backed by the given list.

Only objects of the specified type can be added to the list.

Parameters:

list - the list to limit to a specific type, must not be null

type - the type of objects which may be added to the list

Returns:

a typed list backed by the specified list

transformedList

public static <I,O> List<O> transformedList(List<I> list,
                                            Transformer<? super I,? extends O> transformer)

Returns a transformed list backed by the given list.

Each object is passed through the transformer as it is added to the List. It is important not to use the original list after invoking this method, as it is a backdoor for adding untransformed objects.

Parameters:

list - the list to predicate, must not be null

transformer - the transformer for the list, must not be null

Returns:

a transformed list backed by the given list

Throws:

IllegalArgumentException - if the List or Transformer is null

lazyList

public static <E> List<E> lazyList(List<E> list,
                                   Factory<? extends E> factory)

Returns a "lazy" list whose elements will be created on demand.

When the index passed to the returned list's get method is greater than the list's size, then the factory will be used to create a new object and that object will be inserted at that index.

For instance:

 Factory factory = new Factory() {
     public Object create() {
         return new Date();
     }
 }
 List lazy = ListUtils.lazyList(new ArrayList(), factory);
 Object obj = lazy.get(3);
 

After the above code is executed, obj will contain a new Date instance. Furthermore, that Date instance is the fourth element in the list. The first, second, and third element are all set to null.

Parameters:

list - the list to make lazy, must not be null

factory - the factory for creating new objects, must not be null

Returns:

a lazy list backed by the given list

Throws:

IllegalArgumentException - if the List or Factory is null

fixedSizeList

public static <E> List<E> fixedSizeList(List<E> list)

Returns a fixed-sized list backed by the given list. Elements may not be added or removed from the returned list, but existing elements can be changed (for instance, via the List.set(int,Object) method).

Parameters:

list - the list whose size to fix, must not be null

Returns:

a fixed-size list backed by that list

Throws:

IllegalArgumentException - if the List is null