com.google.common.collect

Class Lists

java.lang.Object

com.google.common.collect.Lists

@GwtCompatible(emulated=true)
public final class Lists
extends Object

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

See the Guava User Guide article on Lists.

Since:

2.0 (imported from Google Collections Library)

Author:

Kevin Bourrillion, Mike Bostock, Louis Wasserman

Method Summary

Methods

Modifier and Type	Method and Description
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 List<Character>	charactersOf(CharSequence sequence) Returns a view of the specified CharSequence as a List<Character>, viewing sequence as a sequence of Unicode code units.
static ImmutableList<Character>	charactersOf(String string) Returns a view of the specified string as an immutable list of Character values.
static <E> ArrayList<E>	newArrayList() Creates a mutable, empty ArrayList instance.
static <E> ArrayList<E>	newArrayList(E... elements) Creates a mutable ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayList(Iterable<? extends E> elements) Creates a mutable ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayList(Iterator<? extends E> elements) Creates a mutable ArrayList instance containing the given elements.
static <E> ArrayList<E>	newArrayListWithCapacity(int initialArraySize) Creates an ArrayList instance backed by an array of the exact size specified; equivalent to ArrayList.ArrayList(int).
static <E> ArrayList<E>	newArrayListWithExpectedSize(int estimatedSize) Creates an ArrayList instance sized appropriately to hold an estimated number of elements without resizing.
static <E> CopyOnWriteArrayList<E>	newCopyOnWriteArrayList() Creates an empty CopyOnWriteArrayList instance.
static <E> CopyOnWriteArrayList<E>	newCopyOnWriteArrayList(Iterable<? extends E> elements) Creates a CopyOnWriteArrayList instance containing the given elements.
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 <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 <T> List<T>	reverse(List<T> list) Returns a reversed view of the specified list.
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

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayList()

Creates a mutable, empty ArrayList instance.

Note: if mutability is not required, use ImmutableList.of() instead.

Returns:

a new, empty ArrayList

newArrayList

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayList(E... elements)

Creates a mutable ArrayList instance containing the given elements.

Note: if mutability is not required and the elements are non-null, use an overload of ImmutableList.of() (for varargs) or ImmutableList.copyOf(Object[]) (for an array) instead.

Parameters:

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

Returns:

a new ArrayList containing those elements

newArrayList

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayList(Iterable<? extends E> elements)

Creates a mutable ArrayList instance containing the given elements.

Note: if mutability is not required and the elements are non-null, use ImmutableList.copyOf(Iterator) instead.

Parameters:

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

Returns:

a new ArrayList containing those elements

newArrayList

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayList(Iterator<? extends E> elements)

Creates a mutable ArrayList instance containing the given elements.

Note: if mutability is not required and the elements are non-null, use ImmutableList.copyOf(Iterator) instead.

Parameters:

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

Returns:

a new ArrayList containing those elements

newArrayListWithCapacity

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayListWithCapacity(int initialArraySize)

Creates an ArrayList instance backed by an array of the exact size specified; equivalent to ArrayList.ArrayList(int).

Note: if you know the exact size your list will be, consider using a fixed-size list (Arrays.asList(Object[])) or an ImmutableList instead of a growable ArrayList.

Note: If you have only an estimate of the eventual size of the list, consider padding this estimate by a suitable amount, or simply use newArrayListWithExpectedSize(int) instead.

Parameters:

initialArraySize - the exact size of the initial backing array for the returned array list (ArrayList documentation calls this value the "capacity")

Returns:

a new, empty ArrayList which is guaranteed not to resize itself unless its size reaches initialArraySize + 1

Throws:

IllegalArgumentException - if initialArraySize is negative

newArrayListWithExpectedSize

@GwtCompatible(serializable=true)
public static <E> ArrayList<E> newArrayListWithExpectedSize(int estimatedSize)

Creates an ArrayList instance sized appropriately to hold an estimated number of elements without resizing. A small amount of padding is added in case the estimate is low.

Note: If you know the exact number of elements the list will hold, or prefer to calculate your own amount of padding, refer to newArrayListWithCapacity(int).

Parameters:

estimatedSize - an estimate of the eventual List.size() of the new list

Returns:

a new, empty ArrayList, sized appropriately to hold the estimated number of elements

Throws:

IllegalArgumentException - if estimatedSize is negative

newLinkedList

@GwtCompatible(serializable=true)
public static <E> LinkedList<E> newLinkedList()

Creates an empty LinkedList instance.

Note: if you need an immutable empty List, use ImmutableList.of() instead.

Returns:

a new, empty LinkedList

newLinkedList

@GwtCompatible(serializable=true)
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 new LinkedList containing those elements

newCopyOnWriteArrayList

@GwtIncompatible(value="CopyOnWriteArrayList")
public static <E> CopyOnWriteArrayList<E> newCopyOnWriteArrayList()

Creates an empty CopyOnWriteArrayList instance.

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

Returns:

a new, empty CopyOnWriteArrayList

Since:

12.0

newCopyOnWriteArrayList

@GwtIncompatible(value="CopyOnWriteArrayList")
public static <E> CopyOnWriteArrayList<E> newCopyOnWriteArrayList(Iterable<? extends E> elements)

Creates a CopyOnWriteArrayList instance containing the given elements.

Parameters:

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

Returns:

a new CopyOnWriteArrayList containing those elements

Since:

12.0

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 is threadsafe if the supplied list and function are.

If only a Collection or Iterable input is available, use Collections2.transform(java.util.Collection<F>, com.google.common.base.Function<? super F, T>) or Iterables.transform(java.lang.Iterable<F>, com.google.common.base.Function<? super F, ? extends T>).

Note: serializing the returned list is implemented by serializing fromList, its contents, and function -- not by serializing the transformed values. This can lead to surprising behavior, so serializing the returned list is not recommended. Instead, copy the list using ImmutableList.copyOf(Collection) (for example), then serialize the copy. Other methods similar to this do not implement serialization at all for this reason.

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.

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:

IllegalArgumentException - if partitionSize is nonpositive

charactersOf

@Beta
public static ImmutableList<Character> charactersOf(String string)

Returns a view of the specified string as an immutable list of Character values.

Since:

7.0

charactersOf

@Beta
public static List<Character> charactersOf(CharSequence sequence)

Returns a view of the specified CharSequence as a List<Character>, viewing sequence as a sequence of Unicode code units. The view does not support any modification operations, but reflects any changes to the underlying character sequence.

Parameters:

sequence - the character sequence to view as a List of characters

Returns:

an List<Character> view of the character sequence

Since:

7.0

reverse

public static <T> List<T> reverse(List<T> list)

Returns a reversed view of the specified list. For example, Lists.reverse(Arrays.asList(1, 2, 3)) returns a list containing 3, 2, 1. The returned list is backed by this list, so changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.

The returned list is random-access if the specified list is random access.

Since:

7.0