Package org.apache.commons.collections4

# Class ListUtils

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

public class ListUtils extends Object
Provides utility methods and decorators for `List` instances.

Since:
  1.0

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static <T> List<T>`
  `defaultIfNull(List<T> list, List<T> defaultList)`
  Returns either the passed in list, or if the list is `null`, the value of `defaultList`.
  `static <T> List<T>`
  `emptyIfNull(List<T> list)`
  Returns an immutable empty list if the argument is `null`, or the argument itself otherwise.
  `static <E> List<E>`
  `fixedSizeList(List<E> list)`
  Returns a fixed-sized list backed by the given list.
  `static <T> T`
  `getFirst(List<T> list)`
  Gets the first element of a list.
  `static <T> T`
  `getLast(List<T> list)`
  Gets the last element of a list.
  `static int`
  `hashCodeForList(Collection<?> list)`
  Generates a hash code using the algorithm specified in `List.hashCode()`.
  `static <E> int`
  `indexOf(List<E> list, Predicate<E> predicate)`
  Finds the first index in the given List which matches the given predicate.
  `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 boolean`
  `isEqualList(Collection<?> list1, Collection<?> list2)`
  Tests two lists for value-equality as per the equality contract in `List.equals(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>`
  `lazyList(List<E> list, Transformer<Integer,? extends E> transformer)`
  Returns a "lazy" list whose elements will be created on demand.
  `static String`
  `longestCommonSubsequence(CharSequence charSequenceA, CharSequence charSequenceB)`
  Returns the longest common subsequence (LCS) of two `CharSequence` objects.
  `static <E> List<E>`
  `longestCommonSubsequence(List<E> a, List<E> b)`
  Returns the longest common subsequence (LCS) of two sequences (lists).
  `static <E> List<E>`
  `longestCommonSubsequence(List<E> listA, List<E> listB, Equator<? super E> equator)`
  Returns the longest common subsequence (LCS) of two sequences (lists).
  `static <T> List<List<T>>`
  `partition(List<T> list, int size)`
  Returns consecutive `sublists` of a list, each of the same size (the final list may be smaller).
  `static <E> List<E>`
  `predicatedList(List<E> list, Predicate<E> predicate)`
  Returns a predicated (validating) list backed by the given list.
  `static <E> List<E>`
  `removeAll(Collection<E> collection, Collection<?> remove)`
  Removes the elements in `remove` from `collection`.
  `static <E> List<E>`
  `retainAll(Collection<E> collection, Collection<?> retain)`
  Returns a List containing all the elements in `collection` that are also in `retain`.
  `static <E> List<E>`
  `select(Collection<? extends E> inputCollection, Predicate<? super E> predicate)`
  Selects all elements from input collection which match the given predicate into an output list.
  `static <E> List<E>`
  `selectRejected(Collection<? extends E> inputCollection, Predicate<? super E> predicate)`
  Selects all elements from inputCollection which don't match the given predicate into an output collection.
  `static <E> List<E>`
  `subtract(List<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 <E> List<E>`
  `transformedList(List<E> list, Transformer<? super E,? extends E> transformer)`
  Returns a transformed list backed by the given list.
  `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<? extends 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`

- ## Method Details

  - ### defaultIfNull

    public static <T> List<T> defaultIfNull(List<T> list, List<T> defaultList)
    Returns either the passed in list, or if the list is `null`, the value of `defaultList`.
    Type Parameters:
      `T` - The element type.
    Parameters:
      `list` - The list, possibly `null`.
      `defaultList` - The returned values if list is `null`.
    Returns:
      An empty list if the argument is `null`.
    Since:
      4.0

  - ### emptyIfNull

    public static <T> List<T> emptyIfNull(List<T> list)
    Returns an immutable empty list if the argument is `null`, or the argument itself otherwise.
    Type Parameters:
      `T` - The element type.
    Parameters:
      `list` - The list, possibly `null`.
    Returns:
      An empty list if the argument 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).
    Type Parameters:
      `E` - the element type.
    Parameters:
      `list` - The list whose size to fix, must not be null.
    Returns:
      A fixed-size list backed by that list.
    Throws:
      `NullPointerException` - if the List is null.

  - ### getFirst

    public static <T> T getFirst(List<T> list)
    Gets the first element of a list.

    Shorthand for `list.get(0)`

    Type Parameters:
      `T` - The list type.
    Parameters:
      `list` - The list.
    Returns:
      The first element of a list.
    Throws:
      `NullPointerException` - if list is null.
      `IndexOutOfBoundsException` - if the list is empty.
    Since:
      4.5.0-M1
    See Also:
      - `List.get(int)`

  - ### getLast

    public static <T> T getLast(List<T> list)
    Gets the last element of a list.

    Shorthand for `list.get(list.size() - 1)`

    Type Parameters:
      `T` - The list type.
    Parameters:
      `list` - The list.
    Returns:
      The last element of a list.
    Throws:
      `NullPointerException` - if list is null.
      `IndexOutOfBoundsException` - if the list is empty.
    Since:
      4.5.0-M1
    See Also:
      - `List.get(int)`

  - ### 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()`

  - ### indexOf

    public static <E> int indexOf(List<E> list, Predicate<E> predicate)
    Finds the first index in the given List which matches the given predicate.

    If the input List or predicate is null, or no element of the List matches the predicate, -1 is returned.

    Type Parameters:
      `E` - the element type.
    Parameters:
      `list` - The List to search, may be null.
      `predicate` - The predicate to use, may be null.
    Returns:
      The first index of an Object in the List which matches the predicate or -1 if none could be found.

  - ### 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.
    Type Parameters:
      `E` - The element type.
    Parameters:
      `list1` - The first list.
      `list2` - The second list.
    Returns:
      the intersection of those two lists.
    Throws:
      `NullPointerException` - if either list is null.

  - ### isEqualList

    public static boolean isEqualList(Collection<?> list1, Collection<?> list2)
    Tests two lists for value-equality as per the equality contract in `List.equals(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 behavior 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`

  - ### 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<Date> factory = new Factory<Date>() {
             public Date create() {
                 return new Date();
             }
         }
         List<Date> lazy = ListUtils.lazyList(new ArrayList<Date>(), factory);
         Date date = lazy.get(3);

    After the above code is executed, `date` will refer to 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`.

    Type Parameters:
      `E` - The element type.
    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:
      `NullPointerException` - if the List or Factory is null.

  - ### lazyList

    public static <E> List<E> lazyList(List<E> list, Transformer<Integer,? extends E> transformer)
    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 transformer will be used to create a new object and that object will be inserted at that index.

    For instance:

         List<Integer> hours = Arrays.asList(7, 5, 8, 2);

         Transformer<Integer, Date> transformer = input -> LocalDateTime.now().withHour(hours.get(input));

         List<LocalDateTime> lazy = ListUtils.lazyList(new ArrayList<LocalDateTime>(), transformer);

         Date date = lazy.get(3);

    After the above code is executed, `date` will refer to 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`.

    Type Parameters:
      `E` - The element type.
    Parameters:
      `list` - The list to make lazy, must not be null.
      `transformer` - The transformer for creating new objects, must not be null.
    Returns:
      A lazy list backed by the given list.
    Throws:
      `NullPointerException` - if the List or Transformer is null.

  - ### longestCommonSubsequence

    public static String longestCommonSubsequence(CharSequence charSequenceA, CharSequence charSequenceB)
    Returns the longest common subsequence (LCS) of two `CharSequence` objects.

    This is a convenience method for using `longestCommonSubsequence(List, List)` with `CharSequence` instances.

    Parameters:
      `charSequenceA` - The first sequence.
      `charSequenceB` - The second sequence.
    Returns:
      The longest common subsequence as `String`.
    Throws:
      `NullPointerException` - if either sequence is `null`.
    Since:
      4.0

  - ### longestCommonSubsequence

    public static <E> List<E> longestCommonSubsequence(List<E> a, List<E> b)
    Returns the longest common subsequence (LCS) of two sequences (lists).
    Type Parameters:
      `E` - the element type.
    Parameters:
      `a` - The first list.
      `b` - The second list.
    Returns:
      The longest common subsequence.
    Throws:
      `NullPointerException` - if either list is `null`.
    Since:
      4.0

  - ### longestCommonSubsequence

    public static <E> List<E> longestCommonSubsequence(List<E> listA, List<E> listB, Equator<? super E> equator)
    Returns the longest common subsequence (LCS) of two sequences (lists).
    Type Parameters:
      `E` - the element type.
    Parameters:
      `listA` - The first list.
      `listB` - The second list.
      `equator` - The equator used to test object equality.
    Returns:
      The longest common subsequence.
    Throws:
      `NullPointerException` - if either list or the equator is `null`.
    Since:
      4.0

  - ### partition

    public static <T> List<List<T>> partition(List<T> list, int size)
    Returns consecutive `sublists` of a list, each of the same size (the final list may be smaller). For example, partitioning a list containing `[a, b, c, d, e]` with a partition size of 3 yields `[[a, b, c], [d, e]]` -- an outer list containing two inner lists of three and two elements, all in the original order.

    The outer list is unmodifiable, but reflects the latest state of the source list. The inner lists are sublist views of the original list, produced on demand using `List.subList(int, int)`, and are subject to all the usual caveats about modification as explained in that API.

    Adapted from https://github.com/google/guava

    Type Parameters:
      `T` - The element type.
    Parameters:
      `list` - The list to return consecutive sublists of.
      `size` - The desired size of each sublist (the last may be smaller).
    Returns:
      A list of consecutive sublists.
    Throws:
      `NullPointerException` - if list is null.
      `IllegalArgumentException` - if size is not strictly positive.
    Since:
      4.0

  - ### predicatedList

    public static <E> List<E> predicatedList(List<E> list, Predicate<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.

    Type Parameters:
      `E` - The element type.
    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:
      `NullPointerException` - if the List or Predicate is null.

  - ### removeAll

    public static <E> List<E> removeAll(Collection<E> collection, Collection<?> remove)
    Removes the elements in `remove` from `collection`. That is, this method returns a list 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 `collection` 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 (for example O(1)) implementation of `Collection.contains(Object)`.

    Type Parameters:
      `E` - the element type.
    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:
      `NullPointerException` - if either parameter is null.
    Since:
      3.2

  - ### retainAll

    public static <E> List<E> retainAll(Collection<E> collection, 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);`.

    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 (for example O(1)) implementation of `Collection.contains(Object)`.

    Type Parameters:
      `E` - the element type.
    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:
      `NullPointerException` - if either parameter is null.
    Since:
      3.2

  - ### select

    public static <E> List<E> select(Collection<? extends E> inputCollection, Predicate<? super E> predicate)
    Selects all elements from input collection which match the given predicate into an output list.

    A `null` predicate matches no elements.

    Type Parameters:
      `E` - The element type.
    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 list is null
    Since:
      4.0
    See Also:
      - `CollectionUtils.select(Iterable, Predicate)`

  - ### selectRejected

    public static <E> List<E> selectRejected(Collection<? extends E> inputCollection, Predicate<? super E> 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:
      `E` - The element type.
    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:
      `NullPointerException` - if the input collection is null.
    Since:
      4.0
    See Also:
      - `CollectionUtils.selectRejected(Iterable, Predicate)`

  - ### subtract

    public static <E> List<E> subtract(List<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.

    Type Parameters:
      `E` - The element type.
    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.
    Type Parameters:
      `E` - The element type.
    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.

  - ### 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 list'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 is just a wrapper for `Collections.synchronizedList(List)`.

    Type Parameters:
      `E` - The element type.
    Parameters:
      `list` - The list to synchronize, must not be null.
    Returns:
      A synchronized list backed by the given list.
    Throws:
      `NullPointerException` - if the list is null.

  - ### transformedList

    public static <E> List<E> transformedList(List<E> list, Transformer<? super E,? extends E> transformer)
    Returns a transformed list backed by the given list.

    This method returns a new list (decorating the specified list) that will transform any new entries added to it. Existing entries in the specified list will not be transformed.

    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.

    Existing entries in the specified list will not be transformed. If you want that behavior, see `TransformedList.transformedList(java.util.List<E>, org.apache.commons.collections4.Transformer<? super E, ? extends E>)`.

    Type Parameters:
      `E` - The element type.
    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:
      `NullPointerException` - if the List or Transformer 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.
    Type Parameters:
      `E` - The element type.
    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.

  - ### unmodifiableList

    public static <E> List<E> unmodifiableList(List<? extends E> list)
    Returns an unmodifiable list backed by the given list.

    This method uses the implementation in the decorators subpackage.

    Type Parameters:
      `E` - the element type.
    Parameters:
      `list` - The list to make unmodifiable, must not be null.
    Returns:
      An unmodifiable list backed by the given list.
    Throws:
      `NullPointerException` - if the list is null.