com.google.common.collect
Class Lists

java.lang.Object
  com.google.common.collect.Lists

public final class Lists
extends java.lang.Object

Static utility methods pertaining to List instances. Also see this class's counterparts Sets and Maps.

Author:

Kevin Bourrillion, Mike Bostock

Method Summary

static <E> java.util.List<E>	asList(E first, E[] rest) Returns an unmodifiable list containing the specified first element and backed by the specified array of additional elements.
static <E> java.util.List<E>	asList(E first, E second, E[] rest) Returns an unmodifiable list containing the specified first and second element, and backed by the specified array of additional elements.
static <E> java.util.List<E>	immutableList() Returns an immutable List instance with no elements.
static <E> java.util.List<E>	immutableList(E... elements) Returns an immutable List instance containing the given elements.
static <E> java.util.List<E>	immutableList(E element) Returns an immutable List instance with a single element.
static <E> java.util.List<E>	immutableList(java.lang.Iterable<? extends E> iterable) Returns an immutable List instance containing the given elements.
static <E> java.util.List<E>	immutableList(java.util.Iterator<? extends E> iterator) Returns an immutable List instance containing the given elements.
static <E> java.util.ArrayList<E>	newArrayList() Creates an empty ArrayList instance.
static <E> java.util.ArrayList<E>	newArrayList(E... elements) Creates an ArrayList instance containing the given elements.
static <E> java.util.ArrayList<E>	newArrayList(java.lang.Iterable<? extends E> elements) Creates an ArrayList instance containing the given elements.
static <E> java.util.ArrayList<E>	newArrayList(java.util.Iterator<? extends E> elements) Creates an ArrayList instance containing the given elements.
static <E> java.util.ArrayList<E>	newArrayListWithCapacity(int initialCapacity) Creates an ArrayList instance with the given initial capacity.
static <E> java.util.ArrayList<E>	newArrayListWithExpectedSize(int expectedSize) Creates an ArrayList instance with the given expected size.
static <E> java.util.LinkedList<E>	newLinkedList() Creates an empty LinkedList instance.
static <E> java.util.LinkedList<E>	newLinkedList(E... elements) Creates a LinkedList instance containing the given elements.
static <E> java.util.LinkedList<E>	newLinkedList(java.lang.Iterable<? extends E> elements) Creates a LinkedList instance containing the given elements.
static <E> java.util.LinkedList<E>	newLinkedList(java.util.Iterator<? extends E> elements) Creates a LinkedList instance containing the given elements.
static <E extends java.lang.Comparable> java.util.List<E>	sortedCopy(java.lang.Iterable<E> iterable) Returns a copy of the given iterable sorted by the natural ordering of its elements.
static <E> java.util.List<E>	sortedCopy(java.lang.Iterable<E> iterable, java.util.Comparator<? super E> comparator) Returns a copy of the given iterable sorted by an explicit comparator.
static <F,T> java.util.List<T>	transform(java.util.List<F> fromList, Function<? super F,? extends T> function) Returns a list that applies function to each element of fromList.

Methods inherited from class java.lang.Object

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

Method Detail

immutableList

public static <E> java.util.List<E> immutableList(E... elements)

Returns an immutable List instance containing the given elements.

Note: due to a bug in javac 1.5.0_06, we cannot support the following:

List<Base> list = Lists.immutableList(sub1, sub2);

where sub1 and sub2 are references to subtypes of Base, not of Base itself. To get around this, you must use:

List<Base> list = Lists.<Base>immutableList(sub1, sub2);

Parameters:

elements - the elements that the list should contain, in order. If an array is given, its contents may later be altered without affecting the List returned by this method

Returns:

an immutable List instance containing those elements

immutableList

public static <E> java.util.List<E> immutableList(java.lang.Iterable<? extends E> iterable)

Returns an immutable List instance containing the given elements. Note that if the input is an immutable list, the input itself may be returned.

Parameters:

iterable - the elements that the list should contain, in order

Returns:

an immutable List instance containing those elements

immutableList

public static <E> java.util.List<E> immutableList(java.util.Iterator<? extends E> iterator)

Returns an immutable List instance containing the given elements.

Parameters:

iterator - the elements that the list should contain, in order

Returns:

an immutable List instance containing those elements

immutableList

public static <E> java.util.List<E> immutableList()

Returns an immutable List instance with no elements.

Returns:

an immutable empty list

See Also:

Collections.emptyList()

immutableList

public static <E> java.util.List<E> immutableList(@Nullable
                                                  E element)

Returns an immutable List instance with a single element.

Parameters:

element - the lone element to be in the returned list

Returns:

an immutable list containing only the given element

See Also:

Collections.singletonList(T)

newArrayList

public static <E> java.util.ArrayList<E> newArrayList()

Creates an empty ArrayList instance.

Note: if you need an immutable empty list, use Collections.emptyList() instead.

Returns:

a newly-created, initially-empty ArrayList

newArrayList

public static <E> java.util.ArrayList<E> newArrayList(E... elements)

Creates an ArrayList instance containing the given elements.

Note: if you need an immutable List, use ImmutableList instead.

Note: due to a bug in javac 1.5.0_06, we cannot support the following:

List<Base> list = Lists.newArrayList(sub1, sub2);

where sub1 and sub2 are references to subtypes of Base, not of Base itself. To get around this, you must use:

List<Base> list = Lists.<Base>newArrayList(sub1, sub2);

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created ArrayList containing those elements

newArrayList

public static <E> java.util.ArrayList<E> newArrayList(java.lang.Iterable<? extends E> elements)

Creates an ArrayList instance containing the given elements.

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created ArrayList containing those elements

newArrayList

public static <E> java.util.ArrayList<E> newArrayList(java.util.Iterator<? extends E> elements)

Creates an ArrayList instance containing the given elements.

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created ArrayList containing those elements

newArrayListWithCapacity

public static <E> java.util.ArrayList<E> newArrayListWithCapacity(int initialCapacity)

Creates an ArrayList instance with the given initial capacity.

Parameters:

initialCapacity - the initial capacity of the list

Returns:

a newly-created, initially empty ArrayList with the given initial capacity

Throws:

java.lang.IllegalArgumentException - if the specified initial capacity is negative

newArrayListWithExpectedSize

public static <E> java.util.ArrayList<E> newArrayListWithExpectedSize(int expectedSize)

Creates an ArrayList instance with the given expected size.

Parameters:

expectedSize - the expected size of the list

Returns:

a newly-created, initially empty ArrayList with enough capacity for the given expected size

Throws:

java.lang.IllegalArgumentException - if the specified expected size is negative

newLinkedList

public static <E> java.util.LinkedList<E> newLinkedList()

Creates an empty LinkedList instance.

Note: if you need an immutable empty List, use Collections.emptyList() instead.

Returns:

a newly-created, initially-empty LinkedList

newLinkedList

public static <E> java.util.LinkedList<E> newLinkedList(E... elements)

Creates a LinkedList instance containing the given elements.

See the caveat in newArrayList(Object...).

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created LinkedList containing those elements

newLinkedList

public static <E> java.util.LinkedList<E> newLinkedList(java.lang.Iterable<? extends E> elements)

Creates a LinkedList instance containing the given elements.

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created LinkedList containing those elements

newLinkedList

public static <E> java.util.LinkedList<E> newLinkedList(java.util.Iterator<? extends E> elements)

Creates a LinkedList instance containing the given elements.

Parameters:

elements - the elements that the list should contain, in order

Returns:

a newly-created LinkedList containing those elements

sortedCopy

public static <E extends java.lang.Comparable> java.util.List<E> sortedCopy(java.lang.Iterable<E> iterable)

Returns a copy of the given iterable sorted by the natural ordering of its elements. The input is not modified. The returned list is modifiable, serializable, and implements RandomAccess.

Unlike Sets.newTreeSet(Iterable), this method does not collapse equal elements, and the resulting collection does not maintain its own sort order.

Parameters:

iterable - the elements to be copied and sorted

Returns:

a new list containing the given elements in sorted order

Throws:

java.lang.ClassCastException - if iterable contains elements that are not mutually comparable

sortedCopy

public static <E> java.util.List<E> sortedCopy(java.lang.Iterable<E> iterable,
                                               java.util.Comparator<? super E> comparator)

Returns a copy of the given iterable sorted by an explicit comparator. The input is not modified. The returned list is modifiable, serializable, and implements RandomAccess.

Unlike Sets.newTreeSet(Comparator, Iterable), this method does not collapse elements that the comparator treats as equal, and the resulting collection does not maintain its own sort order.

Parameters:

iterable - the elements to be copied and sorted

comparator - a comparator capable of sorting the given elements

Returns:

a new list containing the given elements in sorted order

asList

public static <E> java.util.List<E> asList(@Nullable
                                           E first,
                                           E[] rest)

Returns an unmodifiable list containing the specified first element and backed by the specified array of additional elements. Changes to the rest array will be reflected in the returned list. Unlike Arrays.asList(T...), the returned list is unmodifiable.

This is useful when a varargs method needs to use a signature such as (Foo firstFoo, Foo... moreFoos), in order to avoid overload ambiguity or to enforce a minimum argument count.

The returned list is serializable and implements RandomAccess.

Parameters:

first - the first element

rest - an array of additional elements, possibly empty

Returns:

an unmodifiable list containing the specified elements

asList

public static <E> java.util.List<E> asList(@Nullable
                                           E first,
                                           @Nullable
                                           E second,
                                           E[] rest)

Returns an unmodifiable list containing the specified first and second element, and backed by the specified array of additional elements. Changes to the rest array will be reflected in the returned list. Unlike Arrays.asList(T...), the returned list is unmodifiable.

This is useful when a varargs method needs to use a signature such as (Foo firstFoo, Foo secondFoo, Foo... moreFoos), in order to avoid overload ambiguity or to enforce a minimum argument count.

The returned list is serializable and implements RandomAccess.

Parameters:

first - the first element

second - the second element

rest - an array of additional elements, possibly empty

Returns:

an unmodifiable list containing the specified elements

transform

public static <F,T> java.util.List<T> transform(java.util.List<F> fromList,
                                                Function<? super F,? extends T> function)

Returns a list that applies function to each element of fromList. The returned list is a transformed view of fromList; changes to fromList will be reflected in the returned list and vice versa.

Since functions are not reversible, the transform is one-way and new items cannot be stored in the returned list. The add, addAll and set methods are unsupported in the returned list.

The function is applied lazily, invoked when needed. This is necessary for the returned list to be a view, but it means that the function will be applied many times for bulk operations like List.contains(java.lang.Object) and List.hashCode(). For this to perform well, function should be fast. To avoid lazy evaluation when the returned list doesn't need to be a view, copy the returned list into a new list of your choosing.

If fromList implements RandomAccess, so will the returned list. The returned list always implements Serializable, but serialization will succeed only when fromList and function are serializable. The returned list is threadsafe if the supplied list and function are.