@CheckReturnValue @NullMarked

Package com.google.common.collect

Collection interfaces and implementations, and other utilities for collections. This package is a part of the open-source Guava library.

The classes in this package include:

Immutable collections

These are collections whose contents will never change. They also offer a few additional guarantees (see ImmutableCollection for details). Implementations are available for both the JDK collection types and the Guava collection types (listed below).

Collection types

Multimap

A new type, which is similar to Map, but may contain multiple entries with the same key. Some behaviors of Multimap are left unspecified and are provided only by the subtypes mentioned below.

ListMultimap

An extension of Multimap which permits duplicate entries, supports random access of values for a particular key, and has partially order-dependent equality as defined by ListMultimap.equals(Object). ListMultimap takes its name from the fact that the collection of values associated with a given key fulfills the List contract.

SetMultimap

An extension of Multimap which has order-independent equality and does not allow duplicate entries; that is, while a key may appear twice in a SetMultimap, each must map to a different value. SetMultimap takes its name from the fact that the collection of values associated with a given key fulfills the Set contract.

SortedSetMultimap

An extension of SetMultimap for which the collection values associated with a given key is a SortedSet.

BiMap

An extension of Map that guarantees the uniqueness of its values as well as that of its keys. This is sometimes called an "invertible map," since the restriction on values enables it to support an inverse view -- which is another instance of BiMap.

Table

A new type, which is similar to Map, but which indexes its values by an ordered pair of keys, a row key and column key.

Multiset

An extension of Collection that may contain duplicate values like a List, yet has order-independent equality like a Set. One typical use for a multiset is to represent a histogram.

ClassToInstanceMap

An extension of Map that associates a raw type with an instance of that type.

Ranges

• Range
• RangeMap
• RangeSet
• DiscreteDomain
• ContiguousSet

Classes of static utility methods

• Collections2
• Comparators
• Iterables
• Iterators
• Lists
• Maps
• MoreCollectors
• Multimaps
• Multisets
• ObjectArrays
• Queues
• Sets
• Streams
• Tables

Abstract implementations

• AbstractIterator
• AbstractSequentialIterator
• UnmodifiableIterator
• UnmodifiableListIterator

Forwarding collections

We provide implementations of collections that forward all method calls to a delegate collection by default. Subclasses can override one or more methods to implement the decorator pattern. For an example, see ForwardingCollection.

Other

• EvictingQueue
• Interner, Interners
• MapMaker
• MinMaxPriorityQueue
• PeekingIterator

Interface Summary

Interface	Description
BiMap<K extends @Nullable Object,V extends @Nullable Object>	A bimap (or "bidirectional map") is a map that preserves the uniqueness of its values as well as that of its keys.
ClassToInstanceMap<B extends @Nullable Object>	A map, each entry of which maps a Java raw type to an instance of that type.
Interner<E>	Provides similar behavior to String.intern() for any immutable type.
ListMultimap<K extends @Nullable Object,V extends @Nullable Object>	A Multimap that can hold duplicate key-value pairs and that maintains the insertion ordering of values for a given key.
MapDifference<K extends @Nullable Object,V extends @Nullable Object>	An object representing the differences between two maps.
MapDifference.ValueDifference<V extends @Nullable Object>	A difference between the mappings from two maps with the same key.
Maps.EntryTransformer<K extends @Nullable Object,V1 extends @Nullable Object,V2 extends @Nullable Object>	A transformation of the value of a key-value pair, using both key and value as inputs.
Multimap<K extends @Nullable Object,V extends @Nullable Object>	A collection that maps keys to values, similar to Map, but in which each key may be associated with multiple values.
Multiset<E extends @Nullable Object>	A collection that supports order-independent equality, like Set, but may have duplicate elements.
Multiset.Entry<E extends @Nullable Object>	An unmodifiable element-count pair for a multiset.
PeekingIterator<E extends @Nullable Object>	An iterator that supports a one-element lookahead while iterating.
RangeMap<K extends Comparable,V>	A mapping from disjoint nonempty ranges to non-null values.
RangeSet<C extends Comparable>	A set comprising zero or more nonempty, disconnected ranges of type C.
RowSortedTable<R extends @Nullable Object,C extends @Nullable Object,V extends @Nullable Object>	Interface that extends Table and whose rows are sorted.
SetMultimap<K extends @Nullable Object,V extends @Nullable Object>	A Multimap that cannot hold duplicate key-value pairs.
SortedMapDifference<K extends @Nullable Object,V extends @Nullable Object>	An object representing the differences between two sorted maps.
SortedMultiset<E extends @Nullable Object>	A Multiset which maintains the ordering of its elements, according to either their natural order or an explicit Comparator.
SortedSetMultimap<K extends @Nullable Object,V extends @Nullable Object>	A SetMultimap whose set of values for a given key are kept sorted; that is, they comprise a SortedSet.
Streams.DoubleFunctionWithIndex<R extends @Nullable Object>	An analogue of DoubleFunction also accepting an index.
Streams.FunctionWithIndex<T extends @Nullable Object,R extends @Nullable Object>	An analogue of Function also accepting an index.
Streams.IntFunctionWithIndex<R extends @Nullable Object>	An analogue of IntFunction also accepting an index.
Streams.LongFunctionWithIndex<R extends @Nullable Object>	An analogue of LongFunction also accepting an index.
Table<R extends @Nullable Object,C extends @Nullable Object,V extends @Nullable Object>	A collection that associates an ordered pair of keys, called a row key and a column key, with a single value.
Table.Cell<R extends @Nullable Object,C extends @Nullable Object,V extends @Nullable Object>	Row key / column key / value triplet corresponding to a mapping in a table.

Class Summary

Class	Description
AbstractIterator<T extends @Nullable Object>	This class provides a skeletal implementation of the Iterator interface, to make this interface easier to implement for certain types of data sources.
AbstractSequentialIterator<T>	This class provides a skeletal implementation of the Iterator interface for sequences whose next element can always be derived from the previous element.
ArrayListMultimap<K extends @Nullable Object,V extends @Nullable Object>	Implementation of Multimap that uses an ArrayList to store the values for a given key.
ArrayTable<R,C,V>	Fixed-size Table implementation backed by a two-dimensional array.
Collections2	Provides static methods for working with Collection instances.
Comparators	Provides static methods for working with Comparator instances.
ComparisonChain	A utility for performing a chained comparison statement.
ConcurrentHashMultiset<E>	A multiset that supports concurrent modifications and that provides atomic versions of most Multiset operations (exceptions where noted).
ContiguousSet<C extends Comparable>	A sorted set of contiguous values in a given DiscreteDomain.
DiscreteDomain<C extends Comparable>	A descriptor for a discrete Comparable domain such as all Integer instances.
EnumBiMap<K extends Enum<K>,V extends Enum<V>>	A BiMap backed by two EnumMap instances.
EnumHashBiMap<K extends Enum<K>,V extends @Nullable Object>	A BiMap backed by an EnumMap instance for keys-to-values, and a HashMap instance for values-to-keys.
EnumMultiset<E extends Enum<E>>	Multiset implementation specialized for enum elements, supporting all single-element operations in O(1).
EvictingQueue<E>	A non-blocking queue which automatically evicts elements from the head of the queue when attempting to add new elements onto the queue and it is full.
FluentIterable<E extends @Nullable Object>	A discouraged (but not deprecated) precursor to Java's superior Stream library.
ForwardingBlockingDeque<E>	Deprecated. This class has moved to com.google.common.util.concurrent.
ForwardingCollection<E extends @Nullable Object>	A collection which forwards all its method calls to another collection.
ForwardingConcurrentMap<K,V>	A concurrent map which forwards all its method calls to another concurrent map.
ForwardingDeque<E extends @Nullable Object>	A deque which forwards all its method calls to another deque.
ForwardingIterator<T extends @Nullable Object>	An iterator which forwards all its method calls to another iterator.
ForwardingList<E extends @Nullable Object>	A list which forwards all its method calls to another list.
ForwardingListIterator<E extends @Nullable Object>	A list iterator which forwards all its method calls to another list iterator.
ForwardingListMultimap<K extends @Nullable Object,V extends @Nullable Object>	A list multimap which forwards all its method calls to another list multimap.
ForwardingMap<K extends @Nullable Object,V extends @Nullable Object>	A map which forwards all its method calls to another map.
ForwardingMapEntry<K extends @Nullable Object,V extends @Nullable Object>	A map entry which forwards all its method calls to another map entry.
ForwardingMultimap<K extends @Nullable Object,V extends @Nullable Object>	A multimap which forwards all its method calls to another multimap.
ForwardingMultiset<E extends @Nullable Object>	A multiset which forwards all its method calls to another multiset.
ForwardingNavigableMap<K extends @Nullable Object,V extends @Nullable Object>	A navigable map which forwards all its method calls to another navigable map.
ForwardingNavigableSet<E extends @Nullable Object>	A navigable set which forwards all its method calls to another navigable set.
ForwardingObject	An abstract base class for implementing the decorator pattern.
ForwardingQueue<E extends @Nullable Object>	A queue which forwards all its method calls to another queue.
ForwardingSet<E extends @Nullable Object>	A set which forwards all its method calls to another set.
ForwardingSetMultimap<K extends @Nullable Object,V extends @Nullable Object>	A set multimap which forwards all its method calls to another set multimap.
ForwardingSortedMap<K extends @Nullable Object,V extends @Nullable Object>	A sorted map which forwards all its method calls to another sorted map.
ForwardingSortedMultiset<E extends @Nullable Object>	A sorted multiset which forwards all its method calls to another sorted multiset.
ForwardingSortedSet<E extends @Nullable Object>	A sorted set which forwards all its method calls to another sorted set.
ForwardingSortedSetMultimap<K extends @Nullable Object,V extends @Nullable Object>	A sorted set multimap which forwards all its method calls to another sorted set multimap.
ForwardingTable<R extends @Nullable Object,C extends @Nullable Object,V extends @Nullable Object>	A table which forwards all its method calls to another table.
HashBasedTable<R,C,V>	Implementation of Table using linked hash tables.
HashBiMap<K extends @Nullable Object,V extends @Nullable Object>	A BiMap backed by two hash tables.
HashMultimap<K extends @Nullable Object,V extends @Nullable Object>	Implementation of Multimap using hash tables.
HashMultiset<E extends @Nullable Object>	Multiset implementation backed by a HashMap.
ImmutableBiMap<K,V>	A BiMap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableBiMap.Builder<K,V>	A builder for creating immutable bimap instances, especially public static final bimaps ("constant bimaps").
ImmutableClassToInstanceMap<B>	A ClassToInstanceMap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableClassToInstanceMap.Builder<B>	A builder for creating immutable class-to-instance maps.
ImmutableCollection<E>	A Collection whose contents will never change, and which offers a few additional guarantees detailed below.
ImmutableCollection.Builder<E>	Abstract base class for builders of ImmutableCollection types.
ImmutableList<E>	A List whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableList.Builder<E>	A builder for creating immutable list instances, especially public static final lists ("constant lists").
ImmutableListMultimap<K,V>	A ListMultimap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableListMultimap.Builder<K,V>	A builder for creating immutable ListMultimap instances, especially public static final multimaps ("constant multimaps").
ImmutableMap<K,V>	A Map whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableMap.Builder<K,V>	A builder for creating immutable map instances, especially public static final maps ("constant maps").
ImmutableMultimap<K,V>	A Multimap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableMultimap.Builder<K,V>	A builder for creating immutable multimap instances, especially public static final multimaps ("constant multimaps").
ImmutableMultiset<E>	A Multiset whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableMultiset.Builder<E>	A builder for creating immutable multiset instances, especially public static final multisets ("constant multisets").
ImmutableRangeMap<K extends Comparable<?>,V>	A RangeMap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableRangeMap.Builder<K extends Comparable<?>,V>	A builder for immutable range maps.
ImmutableRangeSet<C extends Comparable>	A RangeSet whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableRangeSet.Builder<C extends Comparable<?>>	A builder for immutable range sets.
ImmutableSet<E>	A Set whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableSet.Builder<E>	A builder for creating ImmutableSet instances.
ImmutableSetMultimap<K,V>	A SetMultimap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableSetMultimap.Builder<K,V>	A builder for creating immutable SetMultimap instances, especially public static final multimaps ("constant multimaps").
ImmutableSortedMap<K,V>	A NavigableMap whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableSortedMap.Builder<K,V>	A builder for creating immutable sorted map instances, especially public static final maps ("constant maps").
ImmutableSortedMultiset<E>	A SortedMultiset whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableSortedMultiset.Builder<E>	A builder for creating immutable multiset instances, especially public static final multisets ("constant multisets").
ImmutableSortedSet<E>	A NavigableSet whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableSortedSet.Builder<E>	A builder for creating immutable sorted set instances, especially public static final sets ("constant sets"), with a given comparator.
ImmutableTable<R,C,V>	A Table whose contents will never change, with many other important properties detailed at ImmutableCollection.
ImmutableTable.Builder<R,C,V>	A builder for creating immutable table instances, especially public static final tables ("constant tables").
Interners	Contains static methods pertaining to instances of Interner.
Interners.InternerBuilder	Builder for Interner instances.
Iterables	An assortment of mainly legacy static utility methods that operate on or return objects of type Iterable.
Iterators	This class contains static utility methods that operate on or return objects of type Iterator.
LinkedHashMultimap<K extends @Nullable Object,V extends @Nullable Object>	Implementation of Multimap that does not allow duplicate key-value entries and that returns collections whose iterators follow the ordering in which the data was added to the multimap.
LinkedHashMultiset<E extends @Nullable Object>	A Multiset implementation with predictable iteration order.
LinkedListMultimap<K extends @Nullable Object,V extends @Nullable Object>	An implementation of ListMultimap that supports deterministic iteration order for both keys and values.
Lists	Static utility methods pertaining to List instances.
MapMaker	A builder of ConcurrentMap instances that can have keys or values automatically wrapped in weak references.
Maps	Static utility methods pertaining to Map instances (including instances of SortedMap, BiMap, etc.).
MinMaxPriorityQueue<E>	A double-ended priority queue, which provides constant-time access to both its least element and its greatest element, as determined by the queue's specified comparator.
MinMaxPriorityQueue.Builder<B>	The builder class used in creation of min-max priority queues.
MoreCollectors	Collectors not present in java.util.stream.Collectors that are not otherwise associated with a com.google.common type.
MultimapBuilder<K0 extends @Nullable Object,V0 extends @Nullable Object>	An immutable builder for Multimap instances, letting you independently select the desired behaviors (for example, ordering) of the backing map and value-collections.
MultimapBuilder.ListMultimapBuilder<K0 extends @Nullable Object,V0 extends @Nullable Object>	A specialization of MultimapBuilder that generates ListMultimap instances.
MultimapBuilder.MultimapBuilderWithKeys<K0 extends @Nullable Object>	An intermediate stage in a MultimapBuilder in which the key-value collection map implementation has been specified, but the value collection implementation has not.
MultimapBuilder.SetMultimapBuilder<K0 extends @Nullable Object,V0 extends @Nullable Object>	A specialization of MultimapBuilder that generates SetMultimap instances.
MultimapBuilder.SortedSetMultimapBuilder<K0 extends @Nullable Object,V0 extends @Nullable Object>	A specialization of MultimapBuilder that generates SortedSetMultimap instances.
Multimaps	Provides static methods acting on or generating a Multimap.
Multisets	Provides static utility methods for creating and working with Multiset instances.
MutableClassToInstanceMap<B extends @Nullable Object>	A mutable class-to-instance map backed by an arbitrary user-provided map.
ObjectArrays	Static utility methods pertaining to object arrays.
Ordering<T extends @Nullable Object>	A comparator, with additional methods to support common operations.
Queues	Static utility methods pertaining to Queue and Deque instances.
Range<C extends Comparable>	A range (or "interval") defines the boundaries around a contiguous span of values of some Comparable type; for example, "integers from 1 to 100 inclusive."
Sets	Static utility methods pertaining to Set instances.
Sets.SetView<E extends @Nullable Object>	An unmodifiable view of a set which may be backed by other sets; this view will change as the backing sets do.
Streams	Static utility methods related to Stream instances.
Tables	Provides static methods that involve a Table.
TreeBasedTable<R,C,V>	Implementation of Table whose row keys and column keys are ordered by their natural ordering or by supplied comparators.
TreeMultimap<K extends @Nullable Object,V extends @Nullable Object>	Implementation of Multimap whose keys and values are ordered by their natural ordering or by supplied comparators.
TreeMultiset<E extends @Nullable Object>	A multiset which maintains the ordering of its elements, according to either their natural order or an explicit Comparator.
TreeRangeMap<K extends Comparable,V>	An implementation of RangeMap based on a TreeMap, supporting all optional operations.
TreeRangeSet<C extends Comparable<?>>	An implementation of RangeSet backed by a TreeMap.
TreeTraverser<T>	Deprecated. Use Traverser instead.
UnmodifiableIterator<E extends @Nullable Object>	An iterator that does not support UnmodifiableIterator.remove().
UnmodifiableListIterator<E extends @Nullable Object>	A list iterator that does not support UnmodifiableIterator.remove(), UnmodifiableListIterator.add(E), or UnmodifiableListIterator.set(E).

Enum Summary

Enum	Description
BoundType	Indicates whether an endpoint of some range is contained in the range itself ("closed") or not ("open").

Exception Summary

Exception	Description
ComputationException	Deprecated. This exception is no longer thrown by com.google.common.