Package com.google.common.collect
Interface BiMap<K extends @Nullable Object,V extends @Nullable Object>
-
- All Superinterfaces:
Map<K,V>
- All Known Implementing Classes:
EnumBiMap
,EnumHashBiMap
,HashBiMap
,ImmutableBiMap
@GwtCompatible public interface BiMap<K extends @Nullable Object,V extends @Nullable Object> extends Map<K,V>
A bimap (or "bidirectional map") is a map that preserves the uniqueness of its values as well as that of its keys. This constraint enables bimaps to support an "inverse view", which is another bimap containing the same entries as this bimap but with reversed keys and values.See the Guava User Guide article on
BiMap
.- Since:
- 2.0
- Author:
- Kevin Bourrillion
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description V
forcePut(K key, V value)
An alternate form ofput
that silently removes any existing entry with the valuevalue
before proceeding with theput(K, V)
operation.BiMap<V,K>
inverse()
Returns the inverse view of this bimap, which maps each of this bimap's values to its associated key.V
put(K key, V value)
Associates the specified value with the specified key in this map (optional operation).void
putAll(Map<? extends K,? extends V> map)
Copies all of the mappings from the specified map to this map (optional operation).Set<V>
values()
Returns aCollection
view of the values contained in this map.-
Methods inherited from interface java.util.Map
clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, entrySet, equals, forEach, get, getOrDefault, hashCode, isEmpty, keySet, merge, putIfAbsent, remove, remove, replace, replace, replaceAll, size
-
-
-
-
Method Detail
-
put
@CanIgnoreReturnValue @CheckForNull V put(K key, V value)
Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A mapm
is said to contain a mapping for a keyk
if and only ifm.containsKey(k)
would returntrue
.)- Specified by:
put
in interfaceMap<K extends @Nullable Object,V extends @Nullable Object>
- Parameters:
key
- key with which the specified value is to be associatedvalue
- value to be associated with the specified key- Returns:
- the previous value associated with
key
, ornull
if there was no mapping forkey
. (Anull
return can also indicate that the map previously associatednull
withkey
, if the implementation supportsnull
values.) - Throws:
IllegalArgumentException
- if the given value is already bound to a different key in this bimap. The bimap will remain unmodified in this event. To avoid this exception, callforcePut(K, V)
instead.
-
forcePut
@CanIgnoreReturnValue @CheckForNull V forcePut(K key, V value)
An alternate form ofput
that silently removes any existing entry with the valuevalue
before proceeding with theput(K, V)
operation. If the bimap previously contained the provided key-value mapping, this method has no effect.Note that a successful call to this method could cause the size of the bimap to increase by one, stay the same, or even decrease by one.
Warning: If an existing entry with this value is removed, the key for that entry is discarded and not returned.
- Parameters:
key
- the key with which the specified value is to be associatedvalue
- the value to be associated with the specified key- Returns:
- the value that was previously associated with the key, or
null
if there was no previous entry. (If the bimap contains null values, thenforcePut
, likeput
, returnsnull
both if the key is absent and if it is present with a null value.)
-
putAll
void putAll(Map<? extends K,? extends V> map)
Copies all of the mappings from the specified map to this map (optional operation). The effect of this call is equivalent to that of callingput(k, v)
on this map once for each mapping from keyk
to valuev
in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.Warning: the results of calling this method may vary depending on the iteration order of
map
.- Specified by:
putAll
in interfaceMap<K extends @Nullable Object,V extends @Nullable Object>
- Parameters:
map
- mappings to be stored in this map- Throws:
IllegalArgumentException
- if an attempt toput
any entry fails. Note that some map entries may have been added to the bimap before the exception was thrown.
-
values
Set<V> values()
Returns aCollection
view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa. If the map is modified while an iteration over the collection is in progress (except through the iterator's ownremove
operation), the results of the iteration are undefined. The collection supports element removal, which removes the corresponding mapping from the map, via theIterator.remove
,Collection.remove
,removeAll
,retainAll
andclear
operations. It does not support theadd
oraddAll
operations.Because a bimap has unique values, this method returns a
Set
, instead of theCollection
specified in theMap
interface.
-
inverse
BiMap<V,K> inverse()
Returns the inverse view of this bimap, which maps each of this bimap's values to its associated key. The two bimaps are backed by the same data; any changes to one will appear in the other.Note:There is no guaranteed correspondence between the iteration order of a bimap and that of its inverse.
- Returns:
- the inverse view of this bimap
-
-