java.util.List
instances. Also see this
class's counterparts Sets
, Maps
and com.google.common.collect.Queues
.
See the Guava User Guide article on
Lists
.
ArrayList
instance.
Note: if mutability is not required, use
instead.
ImmutableList.of()
ArrayList
ArrayList
instance containing the given
elements.
Note: if mutability is not required and the elements are
non-null, use an overload of
(for varargs) or
ImmutableList.of()
(for an array) instead.
ImmutableList.copyOf(java.lang.Object[])
elements
the elements that the list should contain, in orderArrayList
containing those elementsArrayList
instance containing the given
elements.
Note: if mutability is not required and the elements are
non-null, use
instead.
ImmutableList.copyOf(java.util.Iterator)
elements
the elements that the list should contain, in orderArrayList
containing those elementsArrayList
instance containing the given
elements.
Note: if mutability is not required and the elements are
non-null, use
instead.
ImmutableList.copyOf(java.util.Iterator)
elements
the elements that the list should contain, in orderArrayList
containing those elementsArrayList
instance backed by an array of the
exact size specified; equivalent to
java.util.ArrayList.(int)
.
Note: if you know the exact size your list will be, consider
using a fixed-size list (
) or an java.util.Arrays.asList(java.lang.Object[])
instead of a growable ImmutableList
.
java.util.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
instead.
newArrayListWithExpectedSize(int)
initialArraySize
the exact size of the initial backing array for
the returned array list (ArrayList
documentation calls this
value the "capacity")ArrayList
which is guaranteed not to resize
itself unless its size reaches initialArraySize + 1
java.lang.IllegalArgumentException
if initialArraySize
is negativeArrayList
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)
estimatedSize
an estimate of the eventual java.util.List.size()
of
the new listArrayList
, sized appropriately to hold the
estimated number of elementsjava.lang.IllegalArgumentException
if estimatedSize
is negativeLinkedList
instance.
Note: if you need an immutable empty
, use
java.util.List
instead.
ImmutableList.of()
LinkedList
rest
array will be reflected in the returned list. Unlike java.util.Arrays.asList(java.lang.Object[])
, 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
.
java.util.RandomAccess
first
the first elementrest
an array of additional elements, possibly emptyrest
array will be reflected in the returned list. Unlike
java.util.Arrays.asList(java.lang.Object[])
, 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
.
java.util.RandomAccess
first
the first elementsecond
the second elementrest
an array of additional elements, possibly empty Lists.cartesianProduct(ImmutableList.of(
ImmutableList.of(1, 2),
ImmutableList.of("A", "B", "C")))
returns a list containing six lists in the following order:
ImmutableList.of(1, "A")
ImmutableList.of(1, "B")
ImmutableList.of(1, "C")
ImmutableList.of(2, "A")
ImmutableList.of(2, "B")
ImmutableList.of(2, "C")
The result is guaranteed to be in the "traditional", lexicographical order for Cartesian products that you would get from nesting for loops:
for (B b0 : lists.get(0)) {
for (B b1 : lists.get(1)) {
...
ImmutableList<B> tuple = ImmutableList.of(b0, b1, ...);
// operate on tuple
}}
Note that if any input list is empty, the Cartesian product will also be empty. If no lists at all are provided (an empty list), the resulting Cartesian product has one element, an empty list (counter-intuitive, but mathematically consistent).
Performance notes: while the cartesian product of lists of size
m, n, p
is a list of size m x n x p
, its actual memory
consumption is much smaller. When the cartesian product is constructed, the
input lists are merely copied. Only as the resulting list is iterated are
the individual lists created, and these are not retained after iteration.
lists
the lists to choose elements from, in the order that
the elements chosen from those lists should appear in the resulting
lists<B
> any common base class shared by all axes (often just java.lang.Object
)java.lang.IllegalArgumentException
if the size of the cartesian product would
be greater than java.lang.Integer.MAX_VALUE
java.lang.NullPointerException
if lists
, any one of the lists
,
or any element of a provided list is null Lists.cartesianProduct(ImmutableList.of(
ImmutableList.of(1, 2),
ImmutableList.of("A", "B", "C")))
returns a list containing six lists in the following order:
ImmutableList.of(1, "A")
ImmutableList.of(1, "B")
ImmutableList.of(1, "C")
ImmutableList.of(2, "A")
ImmutableList.of(2, "B")
ImmutableList.of(2, "C")
The result is guaranteed to be in the "traditional", lexicographical order for Cartesian products that you would get from nesting for loops:
for (B b0 : lists.get(0)) {
for (B b1 : lists.get(1)) {
...
ImmutableList<B> tuple = ImmutableList.of(b0, b1, ...);
// operate on tuple
}}
Note that if any input list is empty, the Cartesian product will also be empty. If no lists at all are provided (an empty list), the resulting Cartesian product has one element, an empty list (counter-intuitive, but mathematically consistent).
Performance notes: while the cartesian product of lists of size
m, n, p
is a list of size m x n x p
, its actual memory
consumption is much smaller. When the cartesian product is constructed, the
input lists are merely copied. Only as the resulting list is iterated are
the individual lists created, and these are not retained after iteration.
lists
the lists to choose elements from, in the order that
the elements chosen from those lists should appear in the resulting
lists<B
> any common base class shared by all axes (often just java.lang.Object
)java.lang.IllegalArgumentException
if the size of the cartesian product would
be greater than java.lang.Integer.MAX_VALUE
java.lang.NullPointerException
if lists
, any one of the
lists
, or any element of a provided list is nullfunction
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
and
java.util.List.contains(java.lang.Object)
. For this to perform well, java.util.List.hashCode()
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
, so will the
returned list. The returned list is threadsafe if the supplied list and
function are.
java.util.RandomAccess
If only a Collection
or Iterable
input is available, use
or com.google.common.collect.Collections2.transform(java.util.Collection,com.google.common.base.Function)
.
Iterables.transform(java.lang.Iterable,com.google.common.base.Function)
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
(for example),
then serialize the copy. Other methods similar to this do not implement
serialization at all for this reason.
ImmutableList.copyOf(java.util.Collection)
[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
, and are subject
to all the usual caveats about modification as explained in that API.
java.util.List.subList(int,int)
list
the list to return consecutive sublists ofsize
the desired size of each sublist (the last may be
smaller)java.lang.IllegalArgumentException
if partitionSize
is nonpositiveCharSequence
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.
sequence
the character sequence to view as a List
of
charactersList<Character>
view of the character sequenceLists.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.