Class ImmutableMap<K,V>

java.lang.Object

com.google.common.collect.ImmutableMap<K,V>

All Implemented Interfaces:

Serializable, Map<K,V>

Direct Known Subclasses:

ImmutableBiMap, ImmutableSortedMap

@DoNotMock("Use ImmutableMap.of or another implementation")
@GwtCompatible
public abstract class ImmutableMap<K,V>
extends Object
implements Map<K,V>, Serializable

A Map 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

Author:

Jesse Wilson, Kevin Bourrillion

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ImmutableMap.Builder<K,V>	A builder for creating immutable map instances, especially public static final maps ("constant maps").

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K,V>

Method Summary

Modifier and Type	Method	Description
ImmutableSetMultimap<K,V>	asMultimap()	Returns a multimap view of the map.
static <K,V> ImmutableMap.Builder<K,V>	builder()	Returns a new builder.
static <K,V> ImmutableMap.Builder<K,V>	builderWithExpectedSize(int expectedSize)	Returns a new builder, expecting the specified number of entries to be added.
final void	clear()	Deprecated. Unsupported operation.
boolean	containsKey(@Nullable Object key)
boolean	containsValue(@Nullable Object value)
static <K,V> ImmutableMap<K,V>	copyOf(Iterable<? extends Map.Entry<? extends K, ? extends V>> entries)	Returns an immutable map containing the specified entries.
static <K,V> ImmutableMap<K,V>	copyOf(Map<? extends K, ? extends V> map)	Returns an immutable map containing the same entries as map.
ImmutableSet<Map.Entry<K,V>>	entrySet()	Returns an immutable set of the mappings in this map.
boolean	equals(@Nullable Object object)
abstract @Nullable V	get(@Nullable Object key)
final @Nullable V	getOrDefault(@Nullable Object key, @Nullable V defaultValue)
int	hashCode()
boolean	isEmpty()
ImmutableSet<K>	keySet()	Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.
static <K,V> ImmutableMap<K,V>	of()	Returns the empty map.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1)	Returns an immutable map containing a single entry.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10)	Returns an immutable map containing the given entries, in order.
static <K,V> ImmutableMap<K,V>	ofEntries(Map.Entry<? extends K, ? extends V>... entries)	Returns an immutable map containing the given entries, in order.
final @Nullable V	put(K k, V v)	Deprecated. Unsupported operation.
final void	putAll(Map<? extends K, ? extends V> map)	Deprecated. Unsupported operation.
final @Nullable V	remove(@Nullable Object o)	Deprecated. Unsupported operation.
static <T extends @Nullable Object, K, V> Collector<T, ?, ImmutableMap<K,V>>	toImmutableMap(Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction)	Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
static <T extends @Nullable Object, K, V> Collector<T, ?, ImmutableMap<K,V>>	toImmutableMap(Function<? super T, ? extends K> keyFunction, Function<? super T, ? extends V> valueFunction, BinaryOperator<V> mergeFunction)	Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.
String	toString()
ImmutableCollection<V>	values()	Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Map

compute, computeIfAbsent, computeIfPresent, forEach, merge, putIfAbsent, remove, replace, replace, replaceAll, size

Method Details

toImmutableMap

public static <T extends @Nullable Object, K, V>
Collector<T, ?, ImmutableMap<K,V>> toImmutableMap(Function<? super T, ? extends K> keyFunction,
 Function<? super T, ? extends V> valueFunction)

Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements. Entries appear in the result ImmutableMap in encounter order.

If the mapped keys contain duplicates (according to Object.equals(Object), an IllegalArgumentException is thrown when the collection operation is performed. (This differs from the Collector returned by Collectors.toMap(Function, Function), which throws an IllegalStateException.)

Since:

33.2.0 (available since 21.0 in guava-jre)

toImmutableMap

public static <T extends @Nullable Object, K, V>
Collector<T, ?, ImmutableMap<K,V>> toImmutableMap(Function<? super T, ? extends K> keyFunction,
 Function<? super T, ? extends V> valueFunction,
 BinaryOperator<V> mergeFunction)

Returns a Collector that accumulates elements into an ImmutableMap whose keys and values are the result of applying the provided mapping functions to the input elements.

If the mapped keys contain duplicates (according to Object.equals(Object)), the values are merged using the specified merging function. If the merging function returns null, then the collector removes the value that has been computed for the key thus far (though future occurrences of the key would reinsert it).

Entries will appear in the encounter order of the first occurrence of the key.

Since:

33.2.0 (available since 21.0 in guava-jre)

of

public static <K,V> ImmutableMap<K,V> of()

Returns the empty map. This map behaves and performs comparably to Collections.emptyMap(), and is preferable mainly for consistency and maintainability of your code.

Performance note: the instance returned is a singleton.

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1)

Returns an immutable map containing a single entry. This map behaves and performs comparably to Collections.singletonMap(K, V) but will not accept a null key or value. It is preferable mainly for consistency and maintainability of your code.

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5,
 K k6,
 V v6)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5,
 K k6,
 V v6,
 K k7,
 V v7)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5,
 K k6,
 V v6,
 K k7,
 V v7,
 K k8,
 V v8)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5,
 K k6,
 V v6,
 K k7,
 V v7,
 K k8,
 V v8,
 K k9,
 V v9)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

of

public static <K,V> ImmutableMap<K,V> of(K k1,
 V v1,
 K k2,
 V v2,
 K k3,
 V v3,
 K k4,
 V v4,
 K k5,
 V v5,
 K k6,
 V v6,
 K k7,
 V v7,
 K k8,
 V v8,
 K k9,
 V v9,
 K k10,
 V v10)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

ofEntries

@SafeVarargs
public static <K,V> ImmutableMap<K,V> ofEntries(Map.Entry<? extends K, ? extends V>... entries)

Returns an immutable map containing the given entries, in order.

Throws:

IllegalArgumentException - if duplicate keys are provided

Since:

31.0

builder

public static <K,V> ImmutableMap.Builder<K,V> builder()

Returns a new builder. The generated builder is equivalent to the builder created by the ImmutableMap.Builder constructor.

builderWithExpectedSize

public static <K,V> ImmutableMap.Builder<K,V> builderWithExpectedSize(int expectedSize)

Returns a new builder, expecting the specified number of entries to be added.

If expectedSize is exactly the number of entries added to the builder before ImmutableMap.Builder.build(boolean) is called, the builder is likely to perform better than an unsized builder() would have.

It is not specified if any performance benefits apply if expectedSize is close to, but not exactly, the number of entries added to the builder.

Since:

23.1

copyOf

public static <K,V> ImmutableMap<K,V> copyOf(Map<? extends K, ? extends V> map)

Returns an immutable map containing the same entries as map. The returned map iterates over entries in the same order as the entrySet of the original map. If map somehow contains entries with duplicate keys (for example, if it is a SortedMap whose comparator is not consistent with equals), the results of this method are undefined.

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.

Throws:

NullPointerException - if any key or value in map is null

copyOf

public static <K,V> ImmutableMap<K,V> copyOf(Iterable<? extends Map.Entry<? extends K, ? extends V>> entries)

Returns an immutable map containing the specified entries. The returned map iterates over entries in the same order as the original iterable.

Throws:

NullPointerException - if any key, value, or entry is null

IllegalArgumentException - if two entries have the same key

Since:

19.0

put

@CanIgnoreReturnValue
@Deprecated
public final @Nullable V put(K k,
 V v)

Deprecated.

Unsupported operation.

Guaranteed to throw an exception and leave the map unmodified.

Specified by:

put in interface Map<K,V>

Throws:

UnsupportedOperationException - always

remove

@CanIgnoreReturnValue
@Deprecated
public final @Nullable V remove(@Nullable Object o)

Deprecated.

Unsupported operation.

Guaranteed to throw an exception and leave the map unmodified.

Specified by:

remove in interface Map<K,V>

Throws:

UnsupportedOperationException - always

putAll

@Deprecated
public final void putAll(Map<? extends K, ? extends V> map)

Deprecated.

Unsupported operation.

Guaranteed to throw an exception and leave the map unmodified.

Specified by:

putAll in interface Map<K,V>

Throws:

UnsupportedOperationException - always

clear

@Deprecated
public final void clear()

Deprecated.

Unsupported operation.

Guaranteed to throw an exception and leave the map unmodified.

Specified by:

clear in interface Map<K,V>

Throws:

UnsupportedOperationException - always

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Map<K,V>

containsKey

public boolean containsKey(@Nullable Object key)

Specified by:

containsKey in interface Map<K,V>

containsValue

public boolean containsValue(@Nullable Object value)

Specified by:

containsValue in interface Map<K,V>

get

public abstract @Nullable V get(@Nullable Object key)

Specified by:

get in interface Map<K,V>

getOrDefault

public final @Nullable V getOrDefault(@Nullable Object key,
 @Nullable V defaultValue)

See Map.getOrDefault.

Specified by:

getOrDefault in interface Map<K,V>

Since:

23.5 (but since 21.0 in the JRE flavor). Note, however, that Java 8+ users can call this method with any version and flavor of Guava.

entrySet

public ImmutableSet<Map.Entry<K,V>> entrySet()

Returns an immutable set of the mappings in this map. The iteration order is specified by the method used to create this map. Typically, this is insertion order.

Specified by:

entrySet in interface Map<K,V>

keySet

public ImmutableSet<K> keySet()

Returns an immutable set of the keys in this map, in the same order that they appear in entrySet.

Specified by:

keySet in interface Map<K,V>

values

public ImmutableCollection<V> values()

Returns an immutable collection of the values in this map, in the same order that they appear in entrySet.

Specified by:

values in interface Map<K,V>

asMultimap

public ImmutableSetMultimap<K,V> asMultimap()

Returns a multimap view of the map.

Since:

14.0

equals

public boolean equals(@Nullable Object object)

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class Object

hashCode

public int hashCode()

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object