Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.collect
Class Lists

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

    public final class Lists

extends 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> 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 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> 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
`<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 a mutable, empty `ArrayList` instance.

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

  Returns:
    a new, empty `ArrayList`

### newArrayList

    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 `ImmutableList.of(Object[])` instead.

  Parameters:
    `elements` - the elements that the list should contain, in order
  Returns:
    a new `ArrayList` containing those elements

### newArrayList

    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

    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

    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

    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

    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 new, 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 new `LinkedList` containing those elements

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

### 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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD