@GwtCompatible(serializable=true, emulated=true) public abstract class ImmutableList<E> extends ImmutableCollection<E> implements List<E>, RandomAccess
List
whose contents will never change, with many other important properties detailed at
ImmutableCollection
.
See the Guava User Guide article on immutable collections.
ImmutableMap
,
ImmutableSet
,
Serialized FormModifier and Type | Class and Description |
---|---|
static class |
ImmutableList.Builder<E>
A builder for creating immutable list instances, especially
public static final lists
("constant lists"). |
Modifier and Type | Method and Description |
---|---|
void |
add(int index,
E element)
Deprecated.
Unsupported operation.
|
boolean |
addAll(int index,
Collection<? extends E> newElements)
Deprecated.
Unsupported operation.
|
ImmutableList<E> |
asList()
Returns this list instance.
|
static <E> ImmutableList.Builder<E> |
builder()
Returns a new builder.
|
static <E> ImmutableList.Builder<E> |
builderWithExpectedSize(int expectedSize)
Returns a new builder, expecting the specified number of elements to be added.
|
boolean |
contains(@Nullable Object object)
Returns true if this collection contains the specified element.
|
static <E> ImmutableList<E> |
copyOf(Collection<? extends E> elements)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
copyOf(E[] elements)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
copyOf(Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
copyOf(Iterator<? extends E> elements)
Returns an immutable list containing the given elements, in order.
|
boolean |
equals(@Nullable Object obj)
Indicates whether some other object is "equal to" this one.
|
void |
forEach(Consumer<? super E> consumer)
Performs the given action for each element of the
Iterable
until all elements have been processed or the action throws an
exception. |
int |
hashCode()
Returns a hash code value for the object.
|
int |
indexOf(@Nullable Object object)
Returns the index of the first occurrence of the specified element
in this list, or -1 if this list does not contain the element.
|
UnmodifiableIterator<E> |
iterator()
Returns an unmodifiable iterator across the elements in this collection.
|
int |
lastIndexOf(@Nullable Object object)
Returns the index of the last occurrence of the specified element
in this list, or -1 if this list does not contain the element.
|
UnmodifiableListIterator<E> |
listIterator()
Returns a list iterator over the elements in this list (in proper
sequence).
|
UnmodifiableListIterator<E> |
listIterator(int index)
Returns a list iterator over the elements in this list (in proper
sequence), starting at the specified position in the list.
|
static <E> ImmutableList<E> |
of()
Returns the empty immutable list.
|
static <E> ImmutableList<E> |
of(E element)
Returns an immutable list containing a single element.
|
static <E> ImmutableList<E> |
of(E e1,
E e2)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7,
E e8)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7,
E e8,
E e9)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7,
E e8,
E e9,
E e10)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7,
E e8,
E e9,
E e10,
E e11)
Returns an immutable list containing the given elements, in order.
|
static <E> ImmutableList<E> |
of(E e1,
E e2,
E e3,
E e4,
E e5,
E e6,
E e7,
E e8,
E e9,
E e10,
E e11,
E e12,
E... others)
Returns an immutable list containing the given elements, in order.
|
E |
remove(int index)
Deprecated.
Unsupported operation.
|
void |
replaceAll(UnaryOperator<E> operator)
Deprecated.
Unsupported operation.
|
ImmutableList<E> |
reverse()
Returns a view of this immutable list in reverse order.
|
E |
set(int index,
E element)
Deprecated.
Unsupported operation.
|
void |
sort(Comparator<? super E> c)
Deprecated.
Unsupported operation.
|
static <E> ImmutableList<E> |
sortedCopyOf(Comparator<? super E> comparator,
Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in sorted order relative to the
specified comparator.
|
static <E extends Comparable<? super E>> |
sortedCopyOf(Iterable<? extends E> elements)
Returns an immutable list containing the given elements, sorted according to their natural
order.
|
Spliterator<E> |
spliterator()
Creates a
Spliterator over the elements in this collection. |
ImmutableList<E> |
subList(int fromIndex,
int toIndex)
Returns an immutable list of the elements between the specified
fromIndex , inclusive,
and toIndex , exclusive. |
static <E> Collector<E,?,ImmutableList<E>> |
toImmutableList()
Returns a
Collector that accumulates the input elements into a new ImmutableList , in encounter order. |
add, addAll, clear, remove, removeAll, removeIf, retainAll, toArray, toArray
containsAll, isEmpty, size, toString
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
add, addAll, clear, containsAll, get, isEmpty, remove, removeAll, retainAll, size, toArray, toArray
parallelStream, removeIf, stream
public static <E> Collector<E,?,ImmutableList<E>> toImmutableList()
Collector
that accumulates the input elements into a new ImmutableList
, in encounter order.public static <E> ImmutableList<E> of()
Collections.emptyList()
, and is preferable mainly for consistency and maintainability of your
code.public static <E> ImmutableList<E> of(E element)
Collections.singleton(T)
, but will not accept a null element. It is
preferable mainly for consistency and maintainability of your code.NullPointerException
- if element
is nullpublic static <E> ImmutableList<E> of(E e1, E e2)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11)
NullPointerException
- if any element is null@SafeVarargs public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10, E e11, E e12, E... others)
The array others
must not be longer than Integer.MAX_VALUE - 12
.
NullPointerException
- if any element is nullpublic static <E> ImmutableList<E> copyOf(Iterable<? extends E> elements)
elements
is a
Collection
, this method behaves exactly as copyOf(Collection)
; otherwise, it
behaves exactly as copyOf(elements.iterator()
.NullPointerException
- if elements
contains a null elementpublic static <E> ImmutableList<E> copyOf(Collection<? extends E> elements)
Despite the method name, this method attempts to avoid actually copying the data when it is safe to do so. The exact circumstances under which a copy will or will not be performed are undocumented and subject to change.
Note that if list
is a List<String>
, then ImmutableList.copyOf(list)
returns an ImmutableList<String>
containing each of the strings in list
, while
ImmutableList.of(list)} returns an ImmutableList<List<String>>
containing one element
(the given list itself).
This method is safe to use even when elements
is a synchronized or concurrent
collection that is currently being modified by another thread.
NullPointerException
- if elements
contains a null elementpublic static <E> ImmutableList<E> copyOf(Iterator<? extends E> elements)
NullPointerException
- if elements
contains a null elementpublic static <E> ImmutableList<E> copyOf(E[] elements)
NullPointerException
- if elements
contains a null elementpublic static <E extends Comparable<? super E>> ImmutableList<E> sortedCopyOf(Iterable<? extends E> elements)
If your data has no duplicates, or you wish to deduplicate elements, use ImmutableSortedSet.copyOf(elements)
; if you want a List
you can use its asList()
view.
Java 8 users: If you want to convert a Stream
to a sorted
ImmutableList
, use stream.sorted().collect(toImmutableList())
.
NullPointerException
- if any element in the input is nullpublic static <E> ImmutableList<E> sortedCopyOf(Comparator<? super E> comparator, Iterable<? extends E> elements)
If your data has no duplicates, or you wish to deduplicate elements, use ImmutableSortedSet.copyOf(comparator, elements)
; if you want a List
you can use its
asList()
view.
Java 8 users: If you want to convert a Stream
to a sorted
ImmutableList
, use stream.sorted(comparator).collect(toImmutableList())
.
NullPointerException
- if any element in the input is nullpublic UnmodifiableIterator<E> iterator()
ImmutableCollection
public UnmodifiableListIterator<E> listIterator()
java.util.List
listIterator
in interface List<E>
public UnmodifiableListIterator<E> listIterator(int index)
java.util.List
next
.
An initial call to previous
would
return the element with the specified index minus one.listIterator
in interface List<E>
index
- index of the first element to be returned from the
list iterator (by a call to next
)public void forEach(Consumer<? super E> consumer)
java.lang.Iterable
Iterable
until all elements have been processed or the action throws an
exception. Unless otherwise specified by the implementing class,
actions are performed in the order of iteration (if an iteration order
is specified). Exceptions thrown by the action are relayed to the
caller.public int indexOf(@Nullable Object object)
java.util.List
public int lastIndexOf(@Nullable Object object)
java.util.List
lastIndexOf
in interface List<E>
object
- element to search forpublic boolean contains(@Nullable Object object)
java.util.AbstractCollection
This implementation iterates over the elements in the collection, checking each element in turn for equality with the specified element.
contains
in interface Collection<E>
contains
in interface List<E>
contains
in class ImmutableCollection<E>
object
- element whose presence in this collection is to be testedpublic ImmutableList<E> subList(int fromIndex, int toIndex)
fromIndex
, inclusive,
and toIndex
, exclusive. (If fromIndex
and toIndex
are equal, the empty
immutable list is returned.)@CanIgnoreReturnValue @Deprecated public final boolean addAll(int index, Collection<? extends E> newElements)
addAll
in interface List<E>
index
- index at which to insert the first element from the
specified collectionnewElements
- collection containing elements to be added to this listUnsupportedOperationException
- always@CanIgnoreReturnValue @Deprecated public final E set(int index, E element)
set
in interface List<E>
index
- index of the element to replaceelement
- element to be stored at the specified positionUnsupportedOperationException
- always@Deprecated public final void add(int index, E element)
add
in interface List<E>
index
- index at which the specified element is to be insertedelement
- element to be insertedUnsupportedOperationException
- always@CanIgnoreReturnValue @Deprecated public final E remove(int index)
remove
in interface List<E>
index
- the index of the element to be removedUnsupportedOperationException
- always@Deprecated public final void replaceAll(UnaryOperator<E> operator)
replaceAll
in interface List<E>
operator
- the operator to apply to each elementUnsupportedOperationException
- always@Deprecated public final void sort(Comparator<? super E> c)
sort
in interface List<E>
c
- the Comparator
used to compare list elements.
A null
value indicates that the elements'
natural ordering should be usedUnsupportedOperationException
- alwayspublic final ImmutableList<E> asList()
asList
in class ImmutableCollection<E>
public Spliterator<E> spliterator()
java.util.Collection
Spliterator
over the elements in this collection.
Implementations should document characteristic values reported by the
spliterator. Such characteristic values are not required to be reported
if the spliterator reports Spliterator.SIZED
and this collection
contains no elements.
The default implementation should be overridden by subclasses that
can return a more efficient spliterator. In order to
preserve expected laziness behavior for the Collection.stream()
and
Collection.parallelStream()
} methods, spliterators should either have the
characteristic of IMMUTABLE
or CONCURRENT
, or be
late-binding.
If none of these is practical, the overriding class should describe the
spliterator's documented policy of binding and structural interference,
and should override the Collection.stream()
and Collection.parallelStream()
methods to create streams using a Supplier
of the spliterator,
as in:
Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)
These requirements ensure that streams produced by the
Collection.stream()
and Collection.parallelStream()
methods will reflect the
contents of the collection as of initiation of the terminal stream
operation.
spliterator
in interface Iterable<E>
spliterator
in interface Collection<E>
spliterator
in interface List<E>
spliterator
in class ImmutableCollection<E>
Spliterator
over the elements in this collectionpublic ImmutableList<E> reverse()
ImmutableList.of(1,
2, 3).reverse()
is equivalent to ImmutableList.of(3, 2, 1)
.public boolean equals(@Nullable Object obj)
java.lang.Object
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y)
consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals
method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode
method whenever this method is overridden, so as to maintain the
general contract for the hashCode
method, which states
that equal objects must have equal hash codes.
equals
in interface Collection<E>
equals
in interface List<E>
equals
in class Object
obj
- the reference object with which to compare.true
if this object is the same as the obj
argument; false
otherwise.Object.hashCode()
,
HashMap
public int hashCode()
java.lang.Object
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
Object.equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
hashCode
in interface Collection<E>
hashCode
in interface List<E>
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public static <E> ImmutableList.Builder<E> builder()
ImmutableList.Builder
constructor.@Beta public static <E> ImmutableList.Builder<E> builderWithExpectedSize(int expectedSize)
If expectedSize
is exactly the number of elements added to the builder before ImmutableList.Builder.build()
is called, the builder is likely to perform better than an unsized builder()
would have.
It is not specified if any performance benefits apply if expectedSize
is close to,
but not exactly, the number of elements added to the builder.
Copyright © 2010–2019. All rights reserved.