Class ImmutableList<E>
- java.lang.Object
-
- java.util.AbstractCollection<E>
-
- com.google.common.collect.ImmutableCollection<E>
-
- com.google.common.collect.ImmutableList<E>
-
- All Implemented Interfaces:
java.io.Serializable
,java.lang.Iterable<E>
,java.util.Collection<E>
,java.util.List<E>
,java.util.RandomAccess
- Direct Known Subclasses:
ImmutableAsList
,ImmutableList.ReverseImmutableList
,ImmutableList.SubList
,ImmutableRangeSet.ComplementRanges
,JdkBackedImmutableBiMap.InverseEntries
,Lists.StringAsImmutableList
,RegularImmutableList
,RegularImmutableMap.Values
,RegularImmutableTable.Values
,SingletonImmutableList
@GwtCompatible(serializable=true, emulated=true) public abstract class ImmutableList<E> extends ImmutableCollection<E> implements java.util.List<E>, java.util.RandomAccess
AList
whose contents will never change, with many other important properties detailed atImmutableCollection
.See the Guava User Guide article on immutable collections.
- Since:
- 2.0
- See Also:
ImmutableMap
,ImmutableSet
, Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
ImmutableList.Builder<E>
A builder for creating immutable list instances, especiallypublic static final
lists ("constant lists").private static class
ImmutableList.ReverseImmutableList<E>
(package private) static class
ImmutableList.SerializedForm
(package private) class
ImmutableList.SubList
-
Field Summary
-
Fields inherited from class com.google.common.collect.ImmutableCollection
SPLITERATOR_CHARACTERISTICS
-
-
Constructor Summary
Constructors Constructor Description ImmutableList()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description void
add(int index, E element)
Deprecated.Unsupported operation.boolean
addAll(int index, java.util.Collection<? extends E> newElements)
Deprecated.Unsupported operation.(package private) static <E> ImmutableList<E>
asImmutableList(java.lang.Object[] elements)
Views the array as an immutable list.(package private) static <E> ImmutableList<E>
asImmutableList(java.lang.Object[] elements, int length)
Views the array as an immutable list.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.private static <E> ImmutableList<E>
construct(java.lang.Object... elements)
Views the array as an immutable list.boolean
contains(java.lang.Object object)
(package private) int
copyIntoArray(java.lang.Object[] dst, int offset)
Copies the contents of this immutable collection into the specified array at the specified offset.static <E> ImmutableList<E>
copyOf(E[] elements)
Returns an immutable list containing the given elements, in order.static <E> ImmutableList<E>
copyOf(java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in order.static <E> ImmutableList<E>
copyOf(java.util.Collection<? extends E> elements)
Returns an immutable list containing the given elements, in order.static <E> ImmutableList<E>
copyOf(java.util.Iterator<? extends E> elements)
Returns an immutable list containing the given elements, in order.boolean
equals(java.lang.Object obj)
void
forEach(java.util.function.Consumer<? super E> consumer)
int
hashCode()
int
indexOf(java.lang.Object object)
UnmodifiableIterator<E>
iterator()
Returns an unmodifiable iterator across the elements in this collection.int
lastIndexOf(java.lang.Object object)
UnmodifiableListIterator<E>
listIterator()
UnmodifiableListIterator<E>
listIterator(int index)
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.private void
readObject(java.io.ObjectInputStream stream)
E
remove(int index)
Deprecated.Unsupported operation.void
replaceAll(java.util.function.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(java.util.Comparator<? super E> c)
Deprecated.Unsupported operation.static <E extends java.lang.Comparable<? super E>>
ImmutableList<E>sortedCopyOf(java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, sorted according to their natural order.static <E> ImmutableList<E>
sortedCopyOf(java.util.Comparator<? super E> comparator, java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in sorted order relative to the specified comparator.java.util.Spliterator<E>
spliterator()
ImmutableList<E>
subList(int fromIndex, int toIndex)
Returns an immutable list of the elements between the specifiedfromIndex
, inclusive, andtoIndex
, exclusive.(package private) ImmutableList<E>
subListUnchecked(int fromIndex, int toIndex)
Called by the default implementation ofsubList(int, int)
whentoIndex - fromIndex > 1
, after index validation has already been performed.static <E> java.util.stream.Collector<E,?,ImmutableList<E>>
toImmutableList()
Returns aCollector
that accumulates the input elements into a newImmutableList
, in encounter order.(package private) java.lang.Object
writeReplace()
-
Methods inherited from class com.google.common.collect.ImmutableCollection
add, addAll, clear, isPartialView, remove, removeAll, removeIf, retainAll, toArray, toArray
-
-
-
-
Method Detail
-
toImmutableList
@Beta public static <E> java.util.stream.Collector<E,?,ImmutableList<E>> toImmutableList()
Returns aCollector
that accumulates the input elements into a newImmutableList
, in encounter order.- Since:
- 21.0
-
of
public static <E> ImmutableList<E> of()
Returns the empty immutable list. This list behaves and performs comparably toCollections.emptyList()
, and is preferable mainly for consistency and maintainability of your code.
-
of
public static <E> ImmutableList<E> of(E element)
Returns an immutable list containing a single element. This list behaves and performs comparably toCollections.singleton(T)
, but will not accept a null element. It is preferable mainly for consistency and maintainability of your code.- Throws:
java.lang.NullPointerException
- ifelement
is null
-
of
public static <E> ImmutableList<E> of(E e1, E e2)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public static <E> ImmutableList<E> of(E e1, E e2, E e3)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public static <E> ImmutableList<E> of(E e1, E e2, E e3, E e4)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public 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.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public 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.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public 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.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public 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.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
public 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.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
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)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
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)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any element is null
-
of
@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)
Returns an immutable list containing the given elements, in order.The array
others
must not be longer thanInteger.MAX_VALUE - 12
.- Throws:
java.lang.NullPointerException
- if any element is null- Since:
- 3.0 (source-compatible since 2.0)
-
copyOf
public static <E> ImmutableList<E> copyOf(java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in order. Ifelements
is aCollection
, this method behaves exactly ascopyOf(Collection)
; otherwise, it behaves exactly ascopyOf(elements.iterator()
.- Throws:
java.lang.NullPointerException
- if any ofelements
is null
-
copyOf
public static <E> ImmutableList<E> copyOf(java.util.Collection<? extends E> elements)
Returns an immutable list containing the given elements, in order.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 aList<String>
, thenImmutableList.copyOf(list)
returns anImmutableList<String>
containing each of the strings inlist
, while ImmutableList.of(list)} returns anImmutableList<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.- Throws:
java.lang.NullPointerException
- if any ofelements
is null
-
copyOf
public static <E> ImmutableList<E> copyOf(java.util.Iterator<? extends E> elements)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any ofelements
is null
-
copyOf
public static <E> ImmutableList<E> copyOf(E[] elements)
Returns an immutable list containing the given elements, in order.- Throws:
java.lang.NullPointerException
- if any ofelements
is null- Since:
- 3.0
-
sortedCopyOf
public static <E extends java.lang.Comparable<? super E>> ImmutableList<E> sortedCopyOf(java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, sorted according to their natural order. The sorting algorithm used is stable, so elements that compare as equal will stay in the order in which they appear in the input.If your data has no duplicates, or you wish to deduplicate elements, use
ImmutableSortedSet.copyOf(elements)
; if you want aList
you can use itsasList()
view.Java 8 users: If you want to convert a
Stream
to a sortedImmutableList
, usestream.sorted().collect(toImmutableList())
.- Throws:
java.lang.NullPointerException
- if any element in the input is null- Since:
- 21.0
-
sortedCopyOf
public static <E> ImmutableList<E> sortedCopyOf(java.util.Comparator<? super E> comparator, java.lang.Iterable<? extends E> elements)
Returns an immutable list containing the given elements, in sorted order relative to the specified comparator. The sorting algorithm used is stable, so elements that compare as equal will stay in the order in which they appear in the input.If your data has no duplicates, or you wish to deduplicate elements, use
ImmutableSortedSet.copyOf(comparator, elements)
; if you want aList
you can use itsasList()
view.Java 8 users: If you want to convert a
Stream
to a sortedImmutableList
, usestream.sorted(comparator).collect(toImmutableList())
.- Throws:
java.lang.NullPointerException
- if any element in the input is null- Since:
- 21.0
-
construct
private static <E> ImmutableList<E> construct(java.lang.Object... elements)
Views the array as an immutable list. Checks for nulls; does not copy.
-
asImmutableList
static <E> ImmutableList<E> asImmutableList(java.lang.Object[] elements)
Views the array as an immutable list. Does not check for nulls; does not copy.The array must be internally created.
-
asImmutableList
static <E> ImmutableList<E> asImmutableList(java.lang.Object[] elements, int length)
Views the array as an immutable list. Copies if the specified range does not cover the complete array. Does not check for nulls.
-
iterator
public UnmodifiableIterator<E> iterator()
Description copied from class:ImmutableCollection
Returns an unmodifiable iterator across the elements in this collection.
-
listIterator
public UnmodifiableListIterator<E> listIterator()
- Specified by:
listIterator
in interfacejava.util.List<E>
-
listIterator
public UnmodifiableListIterator<E> listIterator(int index)
- Specified by:
listIterator
in interfacejava.util.List<E>
-
forEach
public void forEach(java.util.function.Consumer<? super E> consumer)
- Specified by:
forEach
in interfacejava.lang.Iterable<E>
-
indexOf
public int indexOf(java.lang.Object object)
- Specified by:
indexOf
in interfacejava.util.List<E>
-
lastIndexOf
public int lastIndexOf(java.lang.Object object)
- Specified by:
lastIndexOf
in interfacejava.util.List<E>
-
contains
public boolean contains(java.lang.Object object)
- Specified by:
contains
in interfacejava.util.Collection<E>
- Specified by:
contains
in interfacejava.util.List<E>
- Specified by:
contains
in classImmutableCollection<E>
-
subList
public ImmutableList<E> subList(int fromIndex, int toIndex)
Returns an immutable list of the elements between the specifiedfromIndex
, inclusive, andtoIndex
, exclusive. (IffromIndex
andtoIndex
are equal, the empty immutable list is returned.)- Specified by:
subList
in interfacejava.util.List<E>
-
subListUnchecked
ImmutableList<E> subListUnchecked(int fromIndex, int toIndex)
Called by the default implementation ofsubList(int, int)
whentoIndex - fromIndex > 1
, after index validation has already been performed.
-
addAll
@Deprecated public final boolean addAll(int index, java.util.Collection<? extends E> newElements)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
addAll
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
set
@Deprecated public final E set(int index, E element)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
set
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
add
@Deprecated public final void add(int index, E element)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
add
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
remove
@Deprecated public final E remove(int index)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
remove
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
replaceAll
@Deprecated public final void replaceAll(java.util.function.UnaryOperator<E> operator)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
replaceAll
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
sort
@Deprecated public final void sort(java.util.Comparator<? super E> c)
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
sort
in interfacejava.util.List<E>
- Throws:
java.lang.UnsupportedOperationException
- always
-
asList
public final ImmutableList<E> asList()
Returns this list instance.- Overrides:
asList
in classImmutableCollection<E>
- Since:
- 2.0
-
spliterator
public java.util.Spliterator<E> spliterator()
- Specified by:
spliterator
in interfacejava.util.Collection<E>
- Specified by:
spliterator
in interfacejava.lang.Iterable<E>
- Specified by:
spliterator
in interfacejava.util.List<E>
- Overrides:
spliterator
in classImmutableCollection<E>
-
copyIntoArray
int copyIntoArray(java.lang.Object[] dst, int offset)
Description copied from class:ImmutableCollection
Copies the contents of this immutable collection into the specified array at the specified offset. Returnsoffset + size()
.- Overrides:
copyIntoArray
in classImmutableCollection<E>
-
reverse
public ImmutableList<E> reverse()
Returns a view of this immutable list in reverse order. For example,ImmutableList.of(1, 2, 3).reverse()
is equivalent toImmutableList.of(3, 2, 1)
.- Returns:
- a view of this immutable list in reverse order
- Since:
- 7.0
-
equals
public boolean equals(java.lang.Object obj)
-
hashCode
public int hashCode()
-
readObject
private void readObject(java.io.ObjectInputStream stream) throws java.io.InvalidObjectException
- Throws:
java.io.InvalidObjectException
-
writeReplace
java.lang.Object writeReplace()
- Overrides:
writeReplace
in classImmutableCollection<E>
-
builder
public static <E> ImmutableList.Builder<E> builder()
Returns a new builder. The generated builder is equivalent to the builder created by theImmutableList.Builder
constructor.
-
builderWithExpectedSize
@Beta public static <E> ImmutableList.Builder<E> builderWithExpectedSize(int expectedSize)
Returns a new builder, expecting the specified number of elements to be added.If
expectedSize
is exactly the number of elements added to the builder beforeImmutableList.Builder.build()
is called, the builder is likely to perform better than an unsizedbuilder()
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.- Since:
- 23.1
-
-