## org.apache.commons.collections
Class ListUtils

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

    public class ListUtils

extends java.lang.Object

Provides utility methods and decorators for `List` instances.

Since:
  Commons Collections 1.0
Version:
  $Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $
Author:
  Federico Barbieri, Peter Donald, Paul Jack, Stephen Colebourne, Neil O'Toole, Matthew Hawthorne

Field Summary
`static java.util.List` `EMPTY_LIST` An empty unmodifiable list.

Constructor Summary
`ListUtils()` `ListUtils` should not normally be instantiated.

Method Summary
`static java.util.List` `fixedSizeList(java.util.List list)` Returns a fixed-sized list backed by the given list.
`static int` `hashCodeForList(java.util.Collection list)` Generates a hash code using the algorithm specified in `List.hashCode()`.
`static java.util.List` `intersection(java.util.List list1, java.util.List list2)` Returns a new list containing all elements that are contained in both given lists.
`static boolean` `isEqualList(java.util.Collection list1, java.util.Collection list2)` Tests two lists for value-equality as per the equality contract in `List.equals(java.lang.Object)`.
`static java.util.List` `lazyList(java.util.List list, Factory factory)` Returns a "lazy" list whose elements will be created on demand.
`static java.util.List` `predicatedList(java.util.List list, Predicate predicate)` Returns a predicated (validating) list backed by the given list.
`static java.util.List` `removeAll(java.util.Collection collection, java.util.Collection remove)` Removes the elements in `remove` from `collection`.
`static java.util.List` `retainAll(java.util.Collection collection, java.util.Collection retain)` Returns a List containing all the elements in `collection` that are also in `retain`.
`static java.util.List` `subtract(java.util.List list1, java.util.List list2)` Subtracts all elements in the second list from the first list, placing the results in a new list.
`static java.util.List` `sum(java.util.List list1, java.util.List list2)` Returns the sum of the given lists.
`static java.util.List` `synchronizedList(java.util.List list)` Returns a synchronized list backed by the given list.
`static java.util.List` `transformedList(java.util.List list, Transformer transformer)` Returns a transformed list backed by the given list.
`static java.util.List` `typedList(java.util.List list, java.lang.Class type)` Returns a typed list backed by the given list.
`static java.util.List` `union(java.util.List list1, java.util.List list2)` Returns a new list containing the second list appended to the first list.
`static java.util.List` `unmodifiableList(java.util.List 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 java.util.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 java.util.List intersection(java.util.List list1,
                                              java.util.List 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:
    `java.lang.NullPointerException` - if either list is null

### subtract

    public static java.util.List subtract(java.util.List list1,
                                          java.util.List 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:
    `java.lang.NullPointerException` - if either list is null

### sum

    public static java.util.List sum(java.util.List list1,
                                     java.util.List 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:
    `java.lang.NullPointerException` - if either list is null

### union

    public static java.util.List union(java.util.List list1,
                                       java.util.List 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:
    `java.lang.NullPointerException` - if either list is null

### isEqualList

    public static boolean isEqualList(java.util.Collection list1,
                                      java.util.Collection 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(java.util.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()`

### retainAll

    public static java.util.List retainAll(java.util.Collection collection,
                                           java.util.Collection retain)

  Returns a List containing all the elements in `collection` that are also in `retain`. The cardinality of an element `e` in the returned list 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 `collection.retainAll(retain);`.

  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 `List` containing all the elements of `c` that occur at least once in `retain`.
  Throws:
    `java.lang.NullPointerException` - if either parameter is null
  Since:
    Commons Collections 3.2

### removeAll

    public static java.util.List removeAll(java.util.Collection collection,
                                           java.util.Collection remove)

  Removes the elements in `remove` from `collection`. That is, this method returns a list 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 `collection` and thus cannot call `collection.removeAll(remove);`.

  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 `List` containing all the elements of `c` except any elements that also occur in `remove`.
  Throws:
    `java.lang.NullPointerException` - if either parameter is null
  Since:
    Commons Collections 3.2

### synchronizedList

    public static java.util.List synchronizedList(java.util.List 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:
    `java.lang.IllegalArgumentException` - if the list is null

### unmodifiableList

    public static java.util.List unmodifiableList(java.util.List 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:
    `java.lang.IllegalArgumentException` - if the list is null

### predicatedList

    public static java.util.List predicatedList(java.util.List list,
                                                Predicate 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:
    `java.lang.IllegalArgumentException` - if the List or Predicate is null

### typedList

    public static java.util.List typedList(java.util.List list,
                                           java.lang.Class type)

  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 java.util.List transformedList(java.util.List list,
                                                 Transformer 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:
    `java.lang.IllegalArgumentException` - if the List or Transformer is null

### lazyList

    public static java.util.List lazyList(java.util.List list,
                                          Factory 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:
    `java.lang.IllegalArgumentException` - if the List or Factory is null

### fixedSizeList

    public static java.util.List fixedSizeList(java.util.List 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:
    `java.lang.IllegalArgumentException` - if the List is null

Copyright © 2001-2008 The Apache Software Foundation. All Rights Reserved.