com.google.common.collect
Class Lists

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

public final class Lists
extends Object

Provides static methods for creating List instances easily, and other utility methods for working with lists. You can replace code like:

List<String> list = new ArrayList<String>();
Collections.addAll(list, "foo", "bar", "baz");

with just:

List<String> list = newArrayList("foo", "bar", "baz");

You can also create an empty List, or populate your new List using any array, Iterator or Iterable.

Supported today are: ArrayList and LinkedList.

See also this class's counterparts Sets and Maps.

WARNING: These factories do not support the full variety of tuning parameters available in the collection constructors. Use them only for collections which will always remain small, or for which the cost of future growth operations is not a concern.

Author:

Kevin Bourrillion, Mike Bostock

Method Summary

static <E> 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> 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> List<E>	immutableList() Variant of immutableList for zero arguments.
static <E> List<E>	immutableList(Collection<? extends E> collection) Returns an immutable List instance containing the given elements.
static <E> List<E>	immutableList(E... elements) Returns an immutable List instance containing the given elements.
static <E> List<E>	immutableList(E element) Variant of immutableList for one argument.
static <E> List<E>	immutableList(Iterable<? extends E> iterable) Returns an immutable List instance containing the given elements.
static <E> List<E>	immutableList(Iterator<? extends E> iterator) Returns an immutable List instance containing the given elements.
static <E> ArrayList<E>	newArrayList() Creates an empty ArrayList instance.
static <E> ArrayList<E>	newArrayList(E... elements) Creates a resizable ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayList(Iterable<? extends E> elements) Creates an ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayList(Iterator<? extends E> elements) Creates an ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayListWithCapacity(int initialCapacity) Creates an ArrayList instance with the given initial capacity.
static <E> ArrayList<E>	newArrayListWithExpectedSize(int expectedSize) Creates an ArrayList instance with the given expected size.
static <E> LinkedList<E>	newLinkedList() Creates an empty LinkedList instance.
static <E> LinkedList<E>	newLinkedList(E... elements) Creates a LinkedList instance containing the given elements.
static <E> LinkedList<E>	newLinkedList(Iterable<? extends E> elements) Creates a LinkedList instance containing the given elements.
static <E> LinkedList<E>	newLinkedList(Iterator<? extends E> elements) Creates a LinkedList instance containing the given elements.
static <E extends Comparable> List<E>	sortedCopy(Iterable<E> iterable) Returns a copy of the given iterable sorted by the natural ordering of its elements.
static <E> List<E>	sortedCopy(Iterable<E> iterable, Comparator<? super E> comparator) Returns a copy of the given iterable sorted by an explicit comparator.
static <F,T> List<T>	transform(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> 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> List<E> immutableList(Iterable<? extends E> iterable)

Returns an immutable List instance containing the given elements. Note that if the input is an immutable list, then 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> List<E> immutableList(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> List<E> immutableList(Collection<? extends E> collection)

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

Parameters:

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

Returns:

an immutable List instance containing those elements

immutableList

public static <E> List<E> immutableList()

Variant of immutableList for zero arguments.

Returns:

an immutable empty list

See Also:

Collections.emptyList()

immutableList

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

Variant of immutableList for one argument.

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> ArrayList<E> newArrayList()

Creates an empty ArrayList instance.

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

Returns:

a newly-created, initially-empty ArrayList

newArrayList

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

Creates a resizable ArrayList instance containing the given elements.

Note: if it is an immutable List you seek, you should use #immutableList.

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> ArrayList<E> newArrayList(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> ArrayList<E> newArrayList(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> 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:

IllegalArgumentException - if the specified initial capacity is negative

newArrayListWithExpectedSize

public static <E> 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:

IllegalArgumentException - if the specified expected size is negative

newLinkedList

public static <E> LinkedList<E> newLinkedList()

Creates an empty LinkedList instance.

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

Returns:

a newly-created, initially-empty LinkedList

newLinkedList

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

Creates a LinkedList instance containing the given elements.

Please 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> LinkedList<E> newLinkedList(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> LinkedList<E> newLinkedList(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 Comparable> List<E> sortedCopy(Iterable<E> iterable)

Returns a copy of the given iterable sorted by the natural ordering of its elements. The input is not modified.

Unlike Sets.newTreeSet(Iterable), this method does not collapse elements that compare as zero, and the resulting collection does not maintain its own sort order. If you have no preference on these issues, these two alternatives are equivalent, so you can choose for performance factors.

Parameters:

iterable - the elements to be copied and sorted

Returns:

a new list containing the given elements in sorted order

Throws:

ClassCastException - if iterable contains elements which are not mutually comparable

sortedCopy

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

Returns a copy of the given iterable sorted by an explicit comparator. The input is not modified.

Unlike Sets.newTreeSet(Comparator, Iterable), this method does not collapse elements that compare as zero, and the resulting collection does not maintain its own sort order. If you have no preference on these issues, these two alternatives are equivalent, so you can choose for performance factors.

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> 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 (FoofirstFoo,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> 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 (FoofirstFoo,FoosecondFoo,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

transform

public static <F,T> List<T> transform(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, similar to Iterators.transform(java.util.Iterator, com.google.common.base.Function): changes to fromList will be reflected in the returned list and vice versa.

Functions are not reversible, so the transform is one-way and new items cannot be added to the returned list. The add, addAll and set methods are unsupported in the returned list.

As with Iterators.transform(java.util.Iterator, com.google.common.base.Function), the function is applied lazily. This is necessary for returned list to be a view, but also 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. If you want to avoid lazy evaluation and you don't need the returned list to be a view, you can dump the returned list into a new list of your choosing. Alternatively, you can use a memoizing ("canonicalizing") function.

If fromList implements RandomAccess, so will the returned list. TODO: provide similar support for Serializable.