A Collection whose contents will never change, and which offers a few additional guarantees detailed below.

Warning

avoid direct usage of ImmutableCollection as a type (just as with Collection itself). Prefer subtypes such as ImmutableSet or ImmutableList, which have well-defined equals semantics, thus avoiding a common source of bugs and confusion.

About all `Immutable-` collections

The remainder of this documentation applies to every public Immutable- type in this package, whether it is a subtype of ImmutableCollection or not.

Guarantees

Each makes the following guarantees:

Shallow immutability. Elements can never be added, removed or replaced in this collection. This is a stronger guarantee than that of Collections#unmodifiableCollection, whose contents change whenever the wrapped collection is modified.
Null-hostility. This collection will never contain a null element.
Deterministic iteration. The iteration order is always well-defined, depending on how the collection was created. Typically this is insertion order unless an explicit ordering is otherwise specified (e.g. ImmutableSortedSet#naturalOrder). See the appropriate factory method for details. View collections such as ImmutableMultiset#elementSet iterate in the same order as the parent, except as noted.
Thread safety. It is safe to access this collection concurrently from multiple threads.
Integrity. This type cannot be subclassed outside this package (which would allow these guarantees to be violated).

"Interfaces", not implementations

These are classes instead of interfaces to prevent external subtyping, but should be thought of as interfaces in every important sense. Each public class such as ImmutableSet is a type offering meaningful behavioral guarantees. This is substantially different from the case of (say) HashSet, which is an implementation, with semantics that were largely defined by its supertype.

For field types and method return types, you should generally use the immutable type (such as ImmutableList) instead of the general collection interface type (such as List). This communicates to your callers all of the semantic guarantees listed above, which is almost always very useful information.

On the other hand, a parameter type of ImmutableList is generally a nuisance to callers. Instead, accept Iterable and have your method or constructor body pass it to the appropriate copyOf method itself.

Expressing the immutability guarantee directly in the type that user code references is a powerful advantage. Although Java offers certain immutable collection factory methods, such as Collections#singleton(Object) and Set.of, we recommend using these classes instead for this reason (as well as for consistency).

Creation

Except for logically "abstract" types like ImmutableCollection itself, each Immutable type provides the static operations you need to obtain instances of that type. These usually include:

Static methods named of, accepting an explicit list of elements or entries.
Static methods named copyOf (or copyOfSorted), accepting an existing collection whose contents should be copied.
A static nested Builder class which can be used to populate a new immutable instance.

Warnings

Warning: as with any collection, it is almost always a bad idea to modify an element (in a way that affects its Object#equals behavior) while it is contained in a collection. Undefined behavior and bugs will result. It's generally best to avoid using mutable objects as elements at all, as many users may expect your "immutable" object to be deeply immutable.

Performance notes

Implementations can be generally assumed to prioritize memory efficiency, then speed of access, and lastly speed of creation.
The copyOf methods will sometimes recognize that the actual copy operation is unnecessary; for example, copyOf(copyOf(anArrayList)) should copy the data only once. This reduces the expense of habitually making defensive copies at API boundaries. However, the precise conditions for skipping the copy operation are undefined.
Warning: a view collection such as ImmutableMap#keySet or ImmutableList#subList may retain a reference to the entire data set, preventing it from being garbage collected. If some of the data is no longer reachable through other means, this constitutes a memory leak. Pass the view collection to the appropriate copyOf method to obtain a correctly-sized copy.
The performance of using the associated Builder class can be assumed to be no worse, and possibly better, than creating a mutable collection and copying it.
Implementations generally do not cache hash codes. If your element or key type has a slow hashCode implementation, it should cache it itself.

Example usage

class Foo {
  private static final ImmutableSet<String> RESERVED_CODES =
      ImmutableSet.of("AZ", "CQ", "ZX");

  private final ImmutableSet<String> codes;

  public Foo(Iterable<String> codes) {
    this.codes = ImmutableSet.copyOf(codes);
    checkArgument(Collections.disjoint(this.codes, RESERVED_CODES));
  }
}

Nested and Inner Type Summary

Modifier and Type	Class and Description
public abstract static class	ImmutableCollection.Builder<E> Abstract base class for builders of `ImmutableCollection` types.

Field Summary

Modifier and Type	Field and Description
private static final Object[]	EMPTY_ARRAY
private static final long	serialVersionUID
pack-priv static final int	SPLITERATOR_CHARACTERISTICS

Constructor Summary

Access	Constructor and Description
pack-priv	ImmutableCollection()

Method Summary

Modifier and Type	Method and Description
public final boolean	add(E element whose presence in this collection is to be ensured e) Overrides java.util.AbstractCollection.add. Implements java.util.Collection.add. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public final boolean	addAll(Collection<? extends E> collection containing elements to be added to this collection newElements) Overrides java.util.AbstractCollection.addAll. Implements java.util.Collection.addAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public ImmutableList<E>	asList() Returns an `ImmutableList` containing the same elements, in the same order, as this collection.
public final void	clear() Overrides java.util.AbstractCollection.clear. Implements java.util.Collection.clear. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public abstract boolean	contains(Object element whose presence in this collection is to be tested object) Redeclares java.util.Collection.contains. Overrides java.util.AbstractCollection.contains. Returns `true` if this collection contains the specified element.
pack-priv int	copyIntoArray(@Nullable Object[] dst, int offset) Copies the contents of this immutable collection into the specified array at the specified offset.
pack-priv Object[]	internalArray() If this collection is backed by an array of its elements in insertion order, returns it.
pack-priv int	internalArrayEnd() If this collection is backed by an array of its elements in insertion order, returns the offset where this collection's elements end.
pack-priv int	internalArrayStart() If this collection is backed by an array of its elements in insertion order, returns the offset where this collection's elements start.
pack-priv abstract boolean	isPartialView() Returns `true` if this immutable collection's implementation contains references to user-created objects that aren't accessible via this collection's methods.
public abstract UnmodifiableIterator<E>	iterator() Redeclares java.util.Collection.iterator. Implements abstract java.util.AbstractCollection.iterator. Returns an unmodifiable iterator across the elements in this collection.
private void	readObject(ObjectInputStream stream)
public final boolean	remove(Object element to be removed from this collection, if present object) Overrides java.util.AbstractCollection.remove. Implements java.util.Collection.remove. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public final boolean	removeAll(Collection<?> collection containing elements to be removed from this collection oldElements) Overrides java.util.AbstractCollection.removeAll. Implements java.util.Collection.removeAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public final boolean	removeIf(Predicate<? super E> a predicate which returns `true` for elements to be removed filter) Overrides default java.util.Collection.removeIf. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public final boolean	retainAll(Collection<?> collection containing elements to be retained in this collection elementsToKeep) Overrides java.util.AbstractCollection.retainAll. Implements java.util.Collection.retainAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified.
public Spliterator<E>	spliterator() Overrides default java.util.Collection.spliterator. Creates a `Spliterator` over the elements in this collection.
public final Object[]	toArray() Overrides java.util.AbstractCollection.toArray. Implements java.util.Collection.toArray. Returns an array containing all of the elements in this collection.
public final <T extends @Nullable Object> T[]	toArray(T[] the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose. other) Overrides java.util.AbstractCollection.toArray. Implements java.util.Collection.toArray. Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array.
pack-priv Object	writeReplace()

Inherited from java.util.AbstractCollection:: containsAll isEmpty size toString

Field Detail

EMPTY_ARRAY	back to summary
private static final Object[] EMPTY_ARRAY

serialVersionUID	back to summary
private static final long serialVersionUID

SPLITERATOR_CHARACTERISTICS	back to summary
pack-priv static final int SPLITERATOR_CHARACTERISTICS

Constructor Detail

ImmutableCollection	back to summary
pack-priv ImmutableCollection()

Method Detail

add back to summary

add	back to summary
public final boolean add(E e) Overrides java.util.AbstractCollection.add. Implements java.util.Collection.add. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters e:E Doc from java.util.Collection.add. element whose presence in this collection is to be ensured Returns:boolean Doc from java.util.Collection.add. `true` if this collection changed as a result of the call Annotations @CanIgnoreReturnValue @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean add(E e)

Overrides java.util.AbstractCollection.add.

Implements java.util.Collection.add.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

e:E

Doc from java.util.Collection.add.

element whose presence in this collection is to be ensured

Returns:boolean

Doc from java.util.Collection.add.

true if this collection changed as a result of the call

Annotations

@CanIgnoreReturnValue
@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

addAll back to summary

addAll	back to summary
public final boolean addAll(Collection<? extends E> newElements) Overrides java.util.AbstractCollection.addAll. Implements java.util.Collection.addAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters newElements:Collection<? extends E> Doc from java.util.Collection.addAll. collection containing elements to be added to this collection Returns:boolean Doc from java.util.Collection.addAll. `true` if this collection changed as a result of the call Annotations @CanIgnoreReturnValue @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean addAll(Collection<? extends E> newElements)

Overrides java.util.AbstractCollection.addAll.

Implements java.util.Collection.addAll.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

newElements:Collection<? extends E>

Doc from java.util.Collection.addAll.

collection containing elements to be added to this collection

Returns:boolean

Doc from java.util.Collection.addAll.

true if this collection changed as a result of the call

Annotations

@CanIgnoreReturnValue
@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

asList back to summary

asList	back to summary
public ImmutableList<E> asList() Returns an `ImmutableList` containing the same elements, in the same order, as this collection. Performance note: in most cases this method can return quickly without actually copying anything. The exact circumstances under which the copy is performed are undefined and subject to change. Since 2.0

public ImmutableList<E> asList()

Returns an ImmutableList containing the same elements, in the same order, as this collection.

Performance note: in most cases this method can return quickly without actually copying anything. The exact circumstances under which the copy is performed are undefined and subject to change.

Since: 2.0

clear	back to summary
public final void clear() Overrides java.util.AbstractCollection.clear. Implements java.util.Collection.clear. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Annotations @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

clear

back to summary

public final void clear()

Overrides java.util.AbstractCollection.clear.

Implements java.util.Collection.clear.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Annotations

@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

contains back to summary

contains	back to summary
public abstract boolean contains(Object object) Redeclares java.util.Collection.contains. Overrides java.util.AbstractCollection.contains. Doc from java.util.AbstractCollection.contains. Returns `true` if this collection contains the specified element. More formally, returns `true` if and only if this collection contains at least one element `e` such that `Objects.equals(o, e)`. Parameters object:Object Doc from java.util.Collection.contains. element whose presence in this collection is to be tested Returns:boolean Doc from java.util.Collection.contains. `true` if this collection contains the specified element Annotations @Override

public abstract boolean contains(Object object)

Redeclares java.util.Collection.contains.

Overrides java.util.AbstractCollection.contains.

Doc from java.util.AbstractCollection.contains.

Returns true if this collection contains the specified element. More formally, returns true if and only if this collection contains at least one element e such that Objects.equals(o, e).

Parameters

object:Object

Doc from java.util.Collection.contains.

element whose presence in this collection is to be tested

Returns:boolean

Doc from java.util.Collection.contains.

true if this collection contains the specified element

Annotations

@Override

copyIntoArray back to summary

copyIntoArray	back to summary
pack-priv int copyIntoArray(@Nullable Object[] dst, int offset) Copies the contents of this immutable collection into the specified array at the specified offset. Returns `offset + size()`. Annotations @CanIgnoreReturnValue

pack-priv int copyIntoArray(@Nullable Object[] dst, int offset)

Copies the contents of this immutable collection into the specified array at the specified offset. Returns offset + size().

Annotations

@CanIgnoreReturnValue

internalArray	back to summary
pack-priv Object[] internalArray() If this collection is backed by an array of its elements in insertion order, returns it. Annotations @CheckForNull

internalArray

back to summary

pack-priv Object[] internalArray()

If this collection is backed by an array of its elements in insertion order, returns it.

Annotations

@CheckForNull

internalArrayEnd	back to summary
pack-priv int internalArrayEnd() If this collection is backed by an array of its elements in insertion order, returns the offset where this collection's elements end.

internalArrayStart	back to summary
pack-priv int internalArrayStart() If this collection is backed by an array of its elements in insertion order, returns the offset where this collection's elements start.

isPartialView	back to summary
pack-priv abstract boolean isPartialView() Returns `true` if this immutable collection's implementation contains references to user-created objects that aren't accessible via this collection's methods. This is generally used to determine whether `copyOf` implementations should make an explicit copy to avoid memory leaks.

iterator	back to summary
public abstract UnmodifiableIterator<E> iterator() Redeclares java.util.Collection.iterator. Implements abstract java.util.AbstractCollection.iterator. Returns an unmodifiable iterator across the elements in this collection. Returns:UnmodifiableIterator<E> Doc from java.util.AbstractCollection.iterator. an iterator over the elements contained in this collection Annotations @Override

iterator

back to summary

public abstract UnmodifiableIterator<E> iterator()

Redeclares java.util.Collection.iterator.

Implements abstract java.util.AbstractCollection.iterator.

Returns an unmodifiable iterator across the elements in this collection.

Returns:UnmodifiableIterator<E>

Doc from java.util.AbstractCollection.iterator.

an iterator over the elements contained in this collection

Annotations

@Override

readObject	back to summary
private void readObject(ObjectInputStream stream) throws InvalidObjectException Annotations @J2ktIncompatible

remove back to summary

remove	back to summary
public final boolean remove(Object object) Overrides java.util.AbstractCollection.remove. Implements java.util.Collection.remove. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters object:Object Doc from java.util.Collection.remove. element to be removed from this collection, if present Returns:boolean Doc from java.util.Collection.remove. `true` if an element was removed as a result of this call Annotations @CanIgnoreReturnValue @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean remove(Object object)

Overrides java.util.AbstractCollection.remove.

Implements java.util.Collection.remove.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

object:Object

Doc from java.util.Collection.remove.

element to be removed from this collection, if present

Returns:boolean

Doc from java.util.Collection.remove.

true if an element was removed as a result of this call

Annotations

@CanIgnoreReturnValue
@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

removeAll back to summary

removeAll	back to summary
public final boolean removeAll(Collection<?> oldElements) Overrides java.util.AbstractCollection.removeAll. Implements java.util.Collection.removeAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters oldElements:Collection<?> Doc from java.util.Collection.removeAll. collection containing elements to be removed from this collection Returns:boolean Doc from java.util.Collection.removeAll. `true` if this collection changed as a result of the call Annotations @CanIgnoreReturnValue @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean removeAll(Collection<?> oldElements)

Overrides java.util.AbstractCollection.removeAll.

Implements java.util.Collection.removeAll.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

oldElements:Collection<?>

Doc from java.util.Collection.removeAll.

collection containing elements to be removed from this collection

Returns:boolean

Doc from java.util.Collection.removeAll.

true if this collection changed as a result of the call

Annotations

@CanIgnoreReturnValue
@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

removeIf back to summary

removeIf	back to summary
public final boolean removeIf(Predicate<? super E> filter) Overrides default java.util.Collection.removeIf. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters filter:Predicate<? super E> Doc from java.util.Collection.removeIf. a predicate which returns `true` for elements to be removed Returns:boolean Doc from java.util.Collection.removeIf. `true` if any elements were removed Annotations @CanIgnoreReturnValue @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean removeIf(Predicate<? super E> filter)

Overrides default java.util.Collection.removeIf.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

filter:Predicate<? super E>

Doc from java.util.Collection.removeIf.

a predicate which returns true for elements to be removed

Returns:boolean

Doc from java.util.Collection.removeIf.

true if any elements were removed

Annotations

@CanIgnoreReturnValue
@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

retainAll back to summary

retainAll	back to summary
public final boolean retainAll(Collection<?> elementsToKeep) Overrides java.util.AbstractCollection.retainAll. Implements java.util.Collection.retainAll. Deprecated Unsupported operation. Guaranteed to throw an exception and leave the collection unmodified. Parameters elementsToKeep:Collection<?> Doc from java.util.Collection.retainAll. collection containing elements to be retained in this collection Returns:boolean Doc from java.util.Collection.retainAll. `true` if this collection changed as a result of the call Annotations @Deprecated @Override @DoNotCall:Always throws UnsupportedOperationException Exceptions UnsupportedOperationException: always

public final boolean retainAll(Collection<?> elementsToKeep)

Overrides java.util.AbstractCollection.retainAll.

Implements java.util.Collection.retainAll.

Deprecated

Unsupported operation.

Guaranteed to throw an exception and leave the collection unmodified.

Parameters

elementsToKeep:Collection<?>

Doc from java.util.Collection.retainAll.

collection containing elements to be retained in this collection

Returns:boolean

Doc from java.util.Collection.retainAll.

true if this collection changed as a result of the call

Annotations

@Deprecated
@Override
@DoNotCall:Always throws UnsupportedOperationException

Exceptions

UnsupportedOperationException:: always

spliterator back to summary

spliterator	back to summary
public Spliterator<E> spliterator() Overrides default java.util.Collection.spliterator. Doc from java.util.Collection.spliterator. Creates a `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 `stream()` and `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 `stream()` and `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 `stream()` and `parallelStream()` methods will reflect the contents of the collection as of initiation of the terminal stream operation. Returns:Spliterator<E> a `Spliterator` over the elements in this collection Annotations @Override

public Spliterator<E> spliterator()

Overrides default java.util.Collection.spliterator.

Doc from java.util.Collection.spliterator.

Creates a 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 stream() and 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 stream() and 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 stream() and parallelStream() methods will reflect the contents of the collection as of initiation of the terminal stream operation.

Returns:Spliterator<E>

a Spliterator over the elements in this collection

Annotations

@Override

toArray back to summary

toArray	back to summary
public final Object[] toArray() Overrides java.util.AbstractCollection.toArray. Implements java.util.Collection.toArray. Doc from java.util.AbstractCollection.toArray. Returns an array containing all of the elements in this collection. If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array's runtime component type is `Object`. The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array. Returns:Object[] Doc from java.util.Collection.toArray. an array, whose runtime component type is `Object`, containing all of the elements in this collection Annotations @Override @J2ktIncompatible

public final Object[] toArray()

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Doc from java.util.AbstractCollection.toArray.

Returns an array containing all of the elements in this collection. If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array's runtime component type is Object.

The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.

Returns:Object[]

Doc from java.util.Collection.toArray.

an array, whose runtime component type is Object, containing all of the elements in this collection

Annotations

@Override
@J2ktIncompatible

toArray back to summary

toArray	back to summary
public final <T extends @Nullable Object> T[] toArray(T[] other) Overrides java.util.AbstractCollection.toArray. Implements java.util.Collection.toArray. Doc from java.util.AbstractCollection.toArray. Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection. If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to `null`. (This is useful in determining the length of this collection only if the caller knows that this collection does not contain any `null` elements.) If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. Parameters <T> Doc from java.util.Collection.toArray. the component type of the array to contain the collection other:T[] Doc from java.util.Collection.toArray. the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose. Returns:T[] Doc from java.util.Collection.toArray. an array containing all of the elements in this collection Annotations @CanIgnoreReturnValue @Override @SuppressWarnings:nullness

public final <T extends @Nullable Object> T[] toArray(T[] other)

Overrides java.util.AbstractCollection.toArray.

Implements java.util.Collection.toArray.

Doc from java.util.AbstractCollection.toArray.

Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. (This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.)

If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

Parameters

<T>

Doc from java.util.Collection.toArray. the component type of the array to contain the collection

other:T[]

Doc from java.util.Collection.toArray.

the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.

Returns:T[]

Doc from java.util.Collection.toArray.

an array containing all of the elements in this collection

Annotations

@CanIgnoreReturnValue
@Override
@SuppressWarnings:nullness

writeReplace	back to summary
pack-priv Object writeReplace() Annotations @J2ktIncompatible @GwtIncompatible

com.google.common.collect back to summary

public abstract Class ImmutableCollection.Builder<E>

Class Inheritance

extends Object

java.lang.Object
com.google.common.collect.ImmutableCollection.Builder

Known Direct Subclasses

com.google.common.collect.ImmutableList.Builder, com.google.common.collect.ImmutableMultiset.Builder, com.google.common.collect.ImmutableSet.Builder

Annotations

@DoNotMock

Abstract base class for builders of ImmutableCollection types.

Since: 10.0

Field Summary

Modifier and Type	Field and Description
pack-priv static final int	DEFAULT_INITIAL_CAPACITY

Constructor Summary

Access	Constructor and Description
pack-priv	Builder()

Method Summary

Modifier and Type	Method and Description
public abstract ImmutableCollection.Builder<E>	Returns: this `Builder` instance add(E the element to add element) Adds `element` to the `ImmutableCollection` being built.
public ImmutableCollection.Builder<E>	Returns: this `Builder` instance add(E... the elements to add elements) Adds each element of `elements` to the `ImmutableCollection` being built.
public ImmutableCollection.Builder<E>	Returns: this `Builder` instance addAll(Iterable<? extends E> the elements to add elements) Adds each element of `elements` to the `ImmutableCollection` being built.
public ImmutableCollection.Builder<E>	Returns: this `Builder` instance addAll(Iterator<? extends E> the elements to add elements) Adds each element of `elements` to the `ImmutableCollection` being built.
public abstract ImmutableCollection<E>	build() Returns a newly-created `ImmutableCollection` of the appropriate type, containing the elements provided to this builder.
pack-priv static int	expandedCapacity(int oldCapacity, int minCapacity)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

DEFAULT_INITIAL_CAPACITY	back to summary
pack-priv static final int DEFAULT_INITIAL_CAPACITY

Constructor Detail

Builder	back to summary
pack-priv Builder()

Method Detail

add back to summary

add	back to summary
public abstract ImmutableCollection.Builder<E> add(E element) Adds `element` to the `ImmutableCollection` being built. Note that each builder class covariantly returns its own type from this method. Parameters element:E the element to add Returns:ImmutableCollection.Builder<E> this `Builder` instance Annotations @CanIgnoreReturnValue Exceptions NullPointerException: if `element` is null

public abstract ImmutableCollection.Builder<E> add(E element)

Adds element to the ImmutableCollection being built.

Note that each builder class covariantly returns its own type from this method.

Parameters

element:E: the element to add

Returns:ImmutableCollection.Builder<E>

this Builder instance

Annotations

@CanIgnoreReturnValue

Exceptions

NullPointerException:: if element is null

add back to summary

add	back to summary
public ImmutableCollection.Builder<E> add(E... elements) Adds each element of `elements` to the `ImmutableCollection` being built. Note that each builder class overrides this method in order to covariantly return its own type. Parameters elements:E[] the elements to add Returns:ImmutableCollection.Builder<E> this `Builder` instance Annotations @CanIgnoreReturnValue Exceptions NullPointerException: if `elements` is null or contains a null element

public ImmutableCollection.Builder<E> add(E... elements)

Adds each element of elements to the ImmutableCollection being built.

Note that each builder class overrides this method in order to covariantly return its own type.

Parameters

elements:E[]: the elements to add

Returns:ImmutableCollection.Builder<E>

this Builder instance

Annotations

@CanIgnoreReturnValue

Exceptions

NullPointerException:: if elements is null or contains a null element

addAll back to summary

addAll	back to summary
public ImmutableCollection.Builder<E> addAll(Iterable<? extends E> elements) Adds each element of `elements` to the `ImmutableCollection` being built. Note that each builder class overrides this method in order to covariantly return its own type. Parameters elements:Iterable<? extends E> the elements to add Returns:ImmutableCollection.Builder<E> this `Builder` instance Annotations @CanIgnoreReturnValue Exceptions NullPointerException: if `elements` is null or contains a null element

public ImmutableCollection.Builder<E> addAll(Iterable<? extends E> elements)

Adds each element of elements to the ImmutableCollection being built.

Note that each builder class overrides this method in order to covariantly return its own type.

Parameters

elements:Iterable<? extends E>: the elements to add

Returns:ImmutableCollection.Builder<E>

this Builder instance

Annotations

@CanIgnoreReturnValue

Exceptions

NullPointerException:: if elements is null or contains a null element

addAll back to summary

addAll	back to summary
public ImmutableCollection.Builder<E> addAll(Iterator<? extends E> elements) Adds each element of `elements` to the `ImmutableCollection` being built. Note that each builder class overrides this method in order to covariantly return its own type. Parameters elements:Iterator<? extends E> the elements to add Returns:ImmutableCollection.Builder<E> this `Builder` instance Annotations @CanIgnoreReturnValue Exceptions NullPointerException: if `elements` is null or contains a null element

public ImmutableCollection.Builder<E> addAll(Iterator<? extends E> elements)

Adds each element of elements to the ImmutableCollection being built.

Note that each builder class overrides this method in order to covariantly return its own type.

Parameters

elements:Iterator<? extends E>: the elements to add

Returns:ImmutableCollection.Builder<E>

this Builder instance

Annotations

@CanIgnoreReturnValue

Exceptions

NullPointerException:: if elements is null or contains a null element

build back to summary

build	back to summary
public abstract ImmutableCollection<E> build() Returns a newly-created `ImmutableCollection` of the appropriate type, containing the elements provided to this builder. Note that each builder class covariantly returns the appropriate type of `ImmutableCollection` from this method.

public abstract ImmutableCollection<E> build()

Returns a newly-created ImmutableCollection of the appropriate type, containing the elements provided to this builder.

Note that each builder class covariantly returns the appropriate type of ImmutableCollection from this method.

expandedCapacity	back to summary
pack-priv static int expandedCapacity(int oldCapacity, int minCapacity)

public abstract Class ImmutableCollection<E>

About all `Immutable-` collections

Guarantees

"Interfaces", not implementations

Creation

Warnings

Performance notes

Example usage

See also

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public abstract Class ImmutableCollection.Builder<E>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public abstract Class ImmutableCollection<E>

About all Immutable- collections

Guarantees

"Interfaces", not implementations

Creation

Warnings

Performance notes

Example usage

See also

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

public abstract Class ImmutableCollection.Builder<E>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

About all `Immutable-` collections