@GwtCompatible(serializable=true, emulated=true) public abstract class ImmutableMap<K,V> extends Object implements Map<K,V>, Serializable
Map
whose contents will never change, with many other important properties detailed at
ImmutableCollection
.
See the Guava User Guide article on immutable collections.
Modifier and Type | Class and Description |
---|---|
static class |
ImmutableMap.Builder<K,V>
A builder for creating immutable map instances, especially
public static final maps
("constant maps"). |
Modifier and Type | Method and 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.
|
void |
clear()
Deprecated.
Unsupported operation.
|
V |
compute(K key,
BiFunction<? super K,? super V,? extends V> remappingFunction)
Deprecated.
Unsupported operation.
|
V |
computeIfAbsent(K key,
Function<? super K,? extends V> mappingFunction)
Deprecated.
Unsupported operation.
|
V |
computeIfPresent(K key,
BiFunction<? super K,? super V,? extends V> remappingFunction)
Deprecated.
Unsupported operation.
|
boolean |
containsKey(Object key)
Returns true if this map contains a mapping for the specified
key.
|
boolean |
containsValue(Object value)
Returns true if this map maps one or more keys to the
specified 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(Object object)
Indicates whether some other object is "equal to" this one.
|
abstract V |
get(Object key)
Returns the value to which the specified key is mapped,
or
null if this map contains no mapping for the key. |
V |
getOrDefault(Object key,
V defaultValue)
Returns the value to which the specified key is mapped, or
defaultValue if this map contains no mapping for the key. |
int |
hashCode()
Returns a hash code value for the object.
|
boolean |
isEmpty()
Returns true if this map contains no key-value mappings.
|
ImmutableSet<K> |
keySet()
Returns an immutable set of the keys in this map, in the same order that they appear in
entrySet . |
V |
merge(K key,
V value,
BiFunction<? super V,? super V,? extends V> remappingFunction)
Deprecated.
Unsupported operation.
|
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.
|
V |
put(K k,
V v)
Deprecated.
Unsupported operation.
|
void |
putAll(Map<? extends K,? extends V> map)
Deprecated.
Unsupported operation.
|
V |
putIfAbsent(K key,
V value)
Deprecated.
Unsupported operation.
|
V |
remove(Object o)
Deprecated.
Unsupported operation.
|
boolean |
remove(Object key,
Object value)
Deprecated.
Unsupported operation.
|
V |
replace(K key,
V value)
Deprecated.
Unsupported operation.
|
boolean |
replace(K key,
V oldValue,
V newValue)
Deprecated.
Unsupported operation.
|
void |
replaceAll(BiFunction<? super K,? super V,? extends V> function)
Deprecated.
Unsupported operation.
|
static <T,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,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()
Returns a string representation of the object.
|
ImmutableCollection<V> |
values()
Returns an immutable collection of the values in this map, in the same order that they appear
in
entrySet . |
@Beta public static <T,K,V> Collector<T,?,ImmutableMap<K,V>> toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction)
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
.)
@Beta public static <T,K,V> Collector<T,?,ImmutableMap<K,V>> toImmutableMap(Function<? super T,? extends K> keyFunction, Function<? super T,? extends V> valueFunction, BinaryOperator<V> mergeFunction)
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. Entries will appear in the encounter
order of the first occurrence of the key.
public static <K,V> ImmutableMap<K,V> of()
Collections.emptyMap()
, and is preferable mainly for consistency
and maintainability of your code.public static <K,V> ImmutableMap<K,V> of(K k1, V v1)
Collections.singletonMap(K, V)
but will not accept
a null key or value. It is preferable mainly for consistency and
maintainability of your code.public static <K,V> ImmutableMap<K,V> of(K k1, V v1, K k2, V v2)
IllegalArgumentException
- if duplicate keys are providedpublic static <K,V> ImmutableMap<K,V> of(K k1, V v1, K k2, V v2, K k3, V v3)
IllegalArgumentException
- if duplicate keys are providedpublic static <K,V> ImmutableMap<K,V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4)
IllegalArgumentException
- if duplicate keys are providedpublic 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)
IllegalArgumentException
- if duplicate keys are providedpublic static <K,V> ImmutableMap.Builder<K,V> builder()
ImmutableMap.Builder
constructor.@Beta public static <K,V> ImmutableMap.Builder<K,V> builderWithExpectedSize(int expectedSize)
If expectedSize
is exactly the number of entries added to the builder before ImmutableMap.Builder.build()
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.
public static <K,V> ImmutableMap<K,V> copyOf(Map<? extends K,? extends V> map)
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.
NullPointerException
- if any key or value in map
is null@Beta public static <K,V> ImmutableMap<K,V> copyOf(Iterable<? extends Map.Entry<? extends K,? extends V>> entries)
NullPointerException
- if any key, value, or entry is nullIllegalArgumentException
- if two entries have the same key@Deprecated public final V put(K k, V v)
put
in interface Map<K,V>
k
- key with which the specified value is to be associatedv
- value to be associated with the specified keyUnsupportedOperationException
- always@Deprecated public final V putIfAbsent(K key, V value)
putIfAbsent
in interface Map<K,V>
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified keynull
if there was no mapping for the key.
(A null
return can also indicate that the map
previously associated null
with the key,
if the implementation supports null values.)UnsupportedOperationException
- always@Deprecated public final boolean replace(K key, V oldValue, V newValue)
replace
in interface Map<K,V>
key
- key with which the specified value is associatedoldValue
- value expected to be associated with the specified keynewValue
- value to be associated with the specified keytrue
if the value was replacedUnsupportedOperationException
- always@Deprecated public final V replace(K key, V value)
replace
in interface Map<K,V>
key
- key with which the specified value is associatedvalue
- value to be associated with the specified keynull
if there was no mapping for the key.
(A null
return can also indicate that the map
previously associated null
with the key,
if the implementation supports null values.)UnsupportedOperationException
- always@Deprecated public final V computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)
computeIfAbsent
in interface Map<K,V>
key
- key with which the specified value is to be associatedmappingFunction
- the function to compute a valueUnsupportedOperationException
- always@Deprecated public final V computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
computeIfPresent
in interface Map<K,V>
key
- key with which the specified value is to be associatedremappingFunction
- the function to compute a valueUnsupportedOperationException
- always@Deprecated public final V compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)
compute
in interface Map<K,V>
key
- key with which the specified value is to be associatedremappingFunction
- the function to compute a valueUnsupportedOperationException
- always@Deprecated public final V merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)
merge
in interface Map<K,V>
key
- key with which the resulting value is to be associatedvalue
- the non-null value to be merged with the existing value
associated with the key or, if no existing value or a null value
is associated with the key, to be associated with the keyremappingFunction
- the function to recompute a value if presentUnsupportedOperationException
- always@Deprecated public final void putAll(Map<? extends K,? extends V> map)
putAll
in interface Map<K,V>
map
- mappings to be stored in this mapUnsupportedOperationException
- always@Deprecated public final void replaceAll(BiFunction<? super K,? super V,? extends V> function)
replaceAll
in interface Map<K,V>
function
- the function to apply to each entryUnsupportedOperationException
- always@Deprecated public final V remove(Object o)
remove
in interface Map<K,V>
o
- key whose mapping is to be removed from the mapUnsupportedOperationException
- always@Deprecated public final boolean remove(Object key, Object value)
remove
in interface Map<K,V>
key
- key with which the specified value is associatedvalue
- value expected to be associated with the specified keytrue
if the value was removedUnsupportedOperationException
- always@Deprecated public final void clear()
clear
in interface Map<K,V>
UnsupportedOperationException
- alwayspublic boolean isEmpty()
java.util.Map
public boolean containsKey(@Nullable Object key)
java.util.Map
containsKey
in interface Map<K,V>
key
- key whose presence in this map is to be testedpublic boolean containsValue(@Nullable Object value)
java.util.Map
containsValue
in interface Map<K,V>
value
- value whose presence in this map is to be testedpublic abstract V get(@Nullable Object key)
java.util.Map
null
if this map contains no mapping for the key.
More formally, if this map contains a mapping from a key
k
to a value v
such that (key==null ? k==null :
key.equals(k))
, then this method returns v
; otherwise
it returns null
. (There can be at most one such mapping.)
If this map permits null values, then a return value of
null
does not necessarily indicate that the map
contains no mapping for the key; it's also possible that the map
explicitly maps the key to null
. The containsKey
operation may be used to distinguish these two cases.
public final V getOrDefault(@Nullable Object key, @Nullable V defaultValue)
java.util.Map
defaultValue
if this map contains no mapping for the key.getOrDefault
in interface Map<K,V>
key
- the key whose associated value is to be returneddefaultValue
- the default mapping of the keydefaultValue
if this map contains no mapping for the keypublic ImmutableSet<Map.Entry<K,V>> entrySet()
public ImmutableSet<K> keySet()
entrySet
.public ImmutableCollection<V> values()
entrySet
.public ImmutableSetMultimap<K,V> asMultimap()
public boolean equals(@Nullable Object object)
java.lang.Object
The equals
method implements an equivalence relation
on non-null object references:
x
, x.equals(x)
should return
true
.
x
and y
, x.equals(y)
should return true
if and only if
y.equals(x)
returns true
.
x
, y
, and z
, if
x.equals(y)
returns true
and
y.equals(z)
returns true
, then
x.equals(z)
should return true
.
x
and y
, multiple invocations of
x.equals(y)
consistently return true
or consistently return false
, provided no
information used in equals
comparisons on the
objects is modified.
x
,
x.equals(null)
should return false
.
The equals
method for class Object
implements
the most discriminating possible equivalence relation on objects;
that is, for any non-null reference values x
and
y
, this method returns true
if and only
if x
and y
refer to the same object
(x == y
has the value true
).
Note that it is generally necessary to override the hashCode
method whenever this method is overridden, so as to maintain the
general contract for the hashCode
method, which states
that equal objects must have equal hash codes.
public int hashCode()
java.lang.Object
HashMap
.
The general contract of hashCode
is:
hashCode
method
must consistently return the same integer, provided no information
used in equals
comparisons on the object is modified.
This integer need not remain consistent from one execution of an
application to another execution of the same application.
equals(Object)
method, then calling the hashCode
method on each of
the two objects must produce the same integer result.
Object.equals(java.lang.Object)
method, then calling the hashCode
method on each of the
two objects must produce distinct integer results. However, the
programmer should be aware that producing distinct integer results
for unequal objects may improve the performance of hash tables.
As much as is reasonably practical, the hashCode method defined by
class Object
does return distinct integers for distinct
objects. (This is typically implemented by converting the internal
address of the object into an integer, but this implementation
technique is not required by the
Java™ programming language.)
hashCode
in interface Map<K,V>
hashCode
in class Object
Object.equals(java.lang.Object)
,
System.identityHashCode(java.lang.Object)
public String toString()
java.lang.Object
toString
method returns a string that
"textually represents" this object. The result should
be a concise but informative representation that is easy for a
person to read.
It is recommended that all subclasses override this method.
The toString
method for class Object
returns a string consisting of the name of the class of which the
object is an instance, the at-sign character `@
', and
the unsigned hexadecimal representation of the hash code of the
object. In other words, this method returns a string equal to the
value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
Copyright © 2010–2017. All rights reserved.