Class ImmutableList<E>
- All Implemented Interfaces:
Serializable,Iterable<E>,Collection<E>,List<E>,RandomAccess
- Direct Known Subclasses:
ImmutableAsList,ImmutableList.ReverseImmutableList,ImmutableList.SubList,ImmutableRangeSet.ComplementRanges,JdkBackedImmutableBiMap.InverseEntries,Lists.StringAsImmutableList,RegularImmutableList,RegularImmutableMap.Values,RegularImmutableTable.Values,SingletonImmutableList
List whose contents will never change, with many other important properties detailed at
ImmutableCollection.
See the Guava User Guide article on immutable collections.
- Since:
- 2.0
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classA builder for creating immutable list instances, especiallypublic static finallists ("constant lists").private static class(package private) static class(package private) class -
Field Summary
Fields inherited from class com.google.common.collect.ImmutableCollection
SPLITERATOR_CHARACTERISTICS -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal voidDeprecated.Unsupported operation.final booleanaddAll(int index, Collection<? extends E> newElements) Deprecated.Unsupported operation.(package private) static <E> ImmutableList<E>asImmutableList(Object[] elements) Views the array as an immutable list.(package private) static <E> ImmutableList<E>asImmutableList(Object[] elements, int length) Views the array as an immutable list.final ImmutableList<E>asList()Deprecated.There is no reason to use this; it always returnsthis.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>Views the array as an immutable list.boolean(package private) intcopyIntoArray(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>Returns an immutable list containing the given elements, in order.static <E> ImmutableList<E>copyOf(Collection<? extends E> elements) Returns an immutable list containing the given elements, in order.static <E> ImmutableList<E>Returns an immutable list containing the given elements, in order.booleanvoidinthashCode()intiterator()Returns an unmodifiable iterator across the elements in this collection.intlastIndexOf(Object object) 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 voidreadObject(ObjectInputStream stream) final Eremove(int index) Deprecated.Unsupported operation.final voidreplaceAll(UnaryOperator<E> operator) Deprecated.Unsupported operation.reverse()Returns a view of this immutable list in reverse order.final EDeprecated.Unsupported operation.final voidsort(Comparator<? super E> c) Deprecated.Unsupported operation.static <E extends Comparable<? super E>>
ImmutableList<E>sortedCopyOf(Iterable<? extends E> elements) Returns an immutable list containing the given elements, sorted according to their natural order.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.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> Collector<E,?, ImmutableList<E>> Returns aCollectorthat accumulates the input elements into a newImmutableList, in encounter order.(package private) ObjectMethods inherited from class com.google.common.collect.ImmutableCollection
add, addAll, clear, internalArray, internalArrayEnd, internalArrayStart, isPartialView, remove, removeAll, removeIf, retainAll, toArray, toArrayMethods inherited from class java.util.AbstractCollection
containsAll, isEmpty, size, toStringMethods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, waitMethods inherited from interface java.util.Collection
parallelStream, removeIf, stream, toArray
-
Constructor Details
-
ImmutableList
ImmutableList()
-
-
Method Details
-
toImmutableList
Returns aCollectorthat accumulates the input elements into a newImmutableList, in encounter order.- Since:
- 21.0
-
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.Performance note: the instance returned is a singleton.
-
of
Returns an immutable list containing a single element. This list behaves and performs comparably toCollections.singletonList(T), but will not accept a null element. It is preferable mainly for consistency and maintainability of your code.- Throws:
NullPointerException- ifelementis null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- if any element is null
-
of
Returns an immutable list containing the given elements, in order.- Throws:
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:
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
othersmust not be longer thanInteger.MAX_VALUE - 12.- Throws:
NullPointerException- if any element is null- Since:
- 3.0 (source-compatible since 2.0)
-
copyOf
Returns an immutable list containing the given elements, in order. Ifelementsis aCollection, this method behaves exactly ascopyOf(Collection); otherwise, it behaves exactly ascopyOf(elements.iterator().- Throws:
NullPointerException- ifelementscontains a null element
-
copyOf
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
listis aList<String>, thenImmutableList.copyOf(list)returns anImmutableList<String>containing each of the strings inlist, whileImmutableList.of(list)returns anImmutableList<List<String>>containing one element (the given list itself).This method is safe to use even when
elementsis a synchronized or concurrent collection that is currently being modified by another thread.- Throws:
NullPointerException- ifelementscontains a null element
-
copyOf
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- ifelementscontains a null element
-
copyOf
Returns an immutable list containing the given elements, in order.- Throws:
NullPointerException- ifelementscontains a null element- Since:
- 3.0
-
sortedCopyOf
public static <E extends Comparable<? super E>> ImmutableList<E> sortedCopyOf(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 aListyou can use itsasList()view.Java 8 users: If you want to convert a
Streamto a sortedImmutableList, usestream.sorted().collect(toImmutableList()).- Throws:
NullPointerException- if any element in the input is null- Since:
- 21.0
-
sortedCopyOf
public 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. 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 aListyou can use itsasList()view.Java 8 users: If you want to convert a
Streamto a sortedImmutableList, usestream.sorted(comparator).collect(toImmutableList()).- Throws:
NullPointerException- if any element in the input is null- Since:
- 21.0
-
construct
Views the array as an immutable list. Checks for nulls; does not copy. -
asImmutableList
Views the array as an immutable list. Does not check for nulls; does not copy.The array must be internally created.
-
asImmutableList
Views the array as an immutable list. Copies if the specified range does not cover the complete array. Does not check for nulls. -
iterator
Description copied from class:ImmutableCollectionReturns an unmodifiable iterator across the elements in this collection. -
listIterator
- Specified by:
listIteratorin interfaceList<E>
-
listIterator
- Specified by:
listIteratorin interfaceList<E>
-
forEach
-
indexOf
-
lastIndexOf
- Specified by:
lastIndexOfin interfaceList<E>
-
contains
- Specified by:
containsin interfaceCollection<E>- Specified by:
containsin interfaceList<E>- Specified by:
containsin classImmutableCollection<E>
-
subList
Returns an immutable list of the elements between the specifiedfromIndex, inclusive, andtoIndex, exclusive. (IffromIndexandtoIndexare equal, the empty immutable list is returned.) -
subListUnchecked
Called by the default implementation ofsubList(int, int)whentoIndex - fromIndex > 1, after index validation has already been performed. -
addAll
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
addAllin interfaceList<E>- Throws:
UnsupportedOperationException- always
-
set
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
setin interfaceList<E>- Throws:
UnsupportedOperationException- always
-
add
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
addin interfaceList<E>- Throws:
UnsupportedOperationException- always
-
remove
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
removein interfaceList<E>- Throws:
UnsupportedOperationException- always
-
replaceAll
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
replaceAllin interfaceList<E>- Throws:
UnsupportedOperationException- always
-
sort
Deprecated.Unsupported operation.Guaranteed to throw an exception and leave the list unmodified.- Specified by:
sortin interfaceList<E>- Throws:
UnsupportedOperationException- always
-
asList
Deprecated.There is no reason to use this; it always returnsthis.Returns this list instance.- Overrides:
asListin classImmutableCollection<E>- Since:
- 2.0
-
spliterator
- Specified by:
spliteratorin interfaceCollection<E>- Specified by:
spliteratorin interfaceIterable<E>- Specified by:
spliteratorin interfaceList<E>- Overrides:
spliteratorin classImmutableCollection<E>
-
copyIntoArray
Description copied from class:ImmutableCollectionCopies the contents of this immutable collection into the specified array at the specified offset. Returnsoffset + size().- Overrides:
copyIntoArrayin classImmutableCollection<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
-
hashCode
public int hashCode() -
readObject
- Throws:
InvalidObjectException
-
writeReplace
Object writeReplace()- Overrides:
writeReplacein classImmutableCollection<E>
-
builder
Returns a new builder. The generated builder is equivalent to the builder created by theImmutableList.Builderconstructor. -
builderWithExpectedSize
Returns a new builder, expecting the specified number of elements to be added.If
expectedSizeis 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
expectedSizeis close to, but not exactly, the number of elements added to the builder.- Since:
- 23.1
-