com.google.common.collect
Class Lists

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

public final class Lists
extends Object

Provides static methods for creating List instances easily. You can replace code like:

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

with:

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

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

See this class's counterparts Sets and Maps.

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> ArrayList<E>
newArrayList()
          Creates an empty ArrayList instance.
static
<E> ArrayList<E>
newArrayList(E... elements)
          Creates an 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>
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(Iterable<? 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

newArrayList

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

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 need an immutable empty List, use Collections.emptyList() instead.

Returns:
a newly-created, initially-empty LinkedList

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

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 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:
ClassCastException - if iterable contains elements that 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 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> 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> 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> 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; 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.

See Also:
Iterators.transform(java.util.Iterator, com.google.common.base.Function)