com.google.common.collect
Class Maps

java.lang.Object
  com.google.common.collect.Maps

public final class Maps
extends java.lang.Object

Static utility methods pertaining to Map instances. Also see this class's counterparts Lists and Sets.

Author:

Kevin Bourrillion, Mike Bostock

Method Summary

static boolean	containsEntry(java.util.Map<?,?> map, java.lang.Object key, java.lang.Object value) Returns true if map contains an entry mapping key to value.
static java.util.Map<java.lang.String,java.lang.String>	fromProperties(java.util.Properties properties) Creates a Map<String, String> from a Properties instance.
static <K,V> java.util.Map.Entry<K,V>	immutableEntry(K key, V value) Returns an immutable map entry with the specified key and value.
static <B> ClassToInstanceMap<B>	newClassToInstanceMap() Returns a new ClassToInstanceMap instance backed by a HashMap using the default initial capacity and load factor.
static <B> ClassToInstanceMap<B>	newClassToInstanceMap(java.util.Map<java.lang.Class<? extends B>,B> backingMap) Returns a new ClassToInstanceMap instance backed by a given empty backingMap.
static <K,V> java.util.concurrent.ConcurrentHashMap<K,V>	newConcurrentHashMap() Creates a ConcurrentHashMap instance.
static <K extends java.lang.Enum<K>,V extends java.lang.Enum<V>> EnumBiMap<K,V>	newEnumBiMap(java.lang.Class<K> keyType, java.lang.Class<V> valueType) Returns a new empty EnumBiMap using the specified key and value types.
static <K extends java.lang.Enum<K>,V> EnumHashBiMap<K,V>	newEnumHashBiMap(java.lang.Class<K> keyType) Returns a new empty EnumHashBiMap using the specified key type.
static <K extends java.lang.Enum<K>,V> java.util.EnumMap<K,V>	newEnumMap(java.lang.Class<K> type) Creates an EnumMap instance.
static <K,V> HashBiMap<K,V>	newHashBiMap() Returns a new empty HashBiMap with the default initial capacity (16).
static <K,V> java.util.HashMap<K,V>	newHashMap() Creates a HashMap instance.
static <K,V> java.util.HashMap<K,V>	newHashMap(java.util.Map<? extends K,? extends V> map) Creates a HashMap instance with the same mappings as the specified map.
static <K,V> java.util.HashMap<K,V>	newHashMapWithExpectedSize(int expectedSize) Creates a HashMap instance with enough capacity to hold the specified number of elements without rehashing.
static <K,V> java.util.IdentityHashMap<K,V>	newIdentityHashMap() Creates an IdentityHashMap instance.
static <K,V> java.util.LinkedHashMap<K,V>	newLinkedHashMap() Creates an insertion-ordered LinkedHashMap instance.
static <K,V> java.util.LinkedHashMap<K,V>	newLinkedHashMap(java.util.Map<? extends K,? extends V> map) Creates an insertion-ordered LinkedHashMap instance with the same mappings as the specified map.
static <K extends java.lang.Comparable,V> java.util.TreeMap<K,V>	newTreeMap() Creates a TreeMap instance using the natural ordering of its elements.
static <C,K extends C,V> java.util.TreeMap<K,V>	newTreeMap(java.util.Comparator<C> comparator) Creates a TreeMap instance using the given comparator.
static <K,V> BiMap<K,V>	synchronizedBiMap(BiMap<K,V> bimap) Returns a synchronized (thread-safe) bimap backed by the specified bimap.
static <K,V> ImmutableMap<K,V>	uniqueIndex(java.lang.Iterable<V> values, Function<? super V,K> keyFunction) Returns an immutable map for which the Map.values() are the given elements in the given order, and each key is the product of invoking a supplied function on its corresponding value.
static <K,V> BiMap<K,V>	unmodifiableBiMap(BiMap<K,V> bimap) Returns an unmodifiable view of the specified bimap.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

newHashMap

public static <K,V> java.util.HashMap<K,V> newHashMap()

Creates a HashMap instance.

Note: if K is an enum type, use newEnumMap(java.lang.Class) instead.

Note: if you don't actually need the resulting map to be mutable, use Collections.emptyMap() instead.

Returns:

a newly-created, initially-empty HashMap

newHashMapWithExpectedSize

public static <K,V> java.util.HashMap<K,V> newHashMapWithExpectedSize(int expectedSize)

Creates a HashMap instance with enough capacity to hold the specified number of elements without rehashing.

Parameters:

expectedSize - the expected size

Returns:

a newly-created HashMap, initially empty, with enough capacity to hold expectedSize elements without rehashing

Throws:

java.lang.IllegalArgumentException - if expectedSize is negative

newHashMap

public static <K,V> java.util.HashMap<K,V> newHashMap(java.util.Map<? extends K,? extends V> map)

Creates a HashMap instance with the same mappings as the specified map.

Note: if K is an Enum type, use newEnumMap(java.lang.Class) instead.

Parameters:

map - the mappings to be placed in the new map

Returns:

a newly-created HashMap initialized with the mappings from map

newLinkedHashMap

public static <K,V> java.util.LinkedHashMap<K,V> newLinkedHashMap()

Creates an insertion-ordered LinkedHashMap instance.

Returns:

a newly-created, initially-empty LinkedHashMap

newLinkedHashMap

public static <K,V> java.util.LinkedHashMap<K,V> newLinkedHashMap(java.util.Map<? extends K,? extends V> map)

Creates an insertion-ordered LinkedHashMap instance with the same mappings as the specified map.

Parameters:

map - the mappings to be placed in the new map

Returns:

a newly-created, LinkedHashMap initialized with the mappings from map

newConcurrentHashMap

public static <K,V> java.util.concurrent.ConcurrentHashMap<K,V> newConcurrentHashMap()

Creates a ConcurrentHashMap instance.

Returns:

a newly-created, initially-empty ConcurrentHashMap

newTreeMap

public static <K extends java.lang.Comparable,V> java.util.TreeMap<K,V> newTreeMap()

Creates a TreeMap instance using the natural ordering of its elements.

Returns:

a newly-created, initially-empty TreeMap

newTreeMap

public static <C,K extends C,V> java.util.TreeMap<K,V> newTreeMap(@Nullable
                                                                  java.util.Comparator<C> comparator)

Creates a TreeMap instance using the given comparator.

Parameters:

comparator - the comparator to sort the keys with

Returns:

a newly-created, initially-empty TreeMap

newEnumMap

public static <K extends java.lang.Enum<K>,V> java.util.EnumMap<K,V> newEnumMap(java.lang.Class<K> type)

Creates an EnumMap instance.

Parameters:

type - the key type for this map

Returns:

a newly-created, initially-empty EnumMap

newIdentityHashMap

public static <K,V> java.util.IdentityHashMap<K,V> newIdentityHashMap()

Creates an IdentityHashMap instance.

Returns:

a newly-created, initially-empty IdentityHashMap

containsEntry

public static boolean containsEntry(java.util.Map<?,?> map,
                                    @Nullable
                                    java.lang.Object key,
                                    @Nullable
                                    java.lang.Object value)

Returns true if map contains an entry mapping key to value. If you are not concerned with null-safety you can simply use map.get(key).equals(value).

synchronizedBiMap

public static <K,V> BiMap<K,V> synchronizedBiMap(BiMap<K,V> bimap)

Returns a synchronized (thread-safe) bimap backed by the specified bimap. In order to guarantee serial access, it is critical that all access to the backing bimap is accomplished through the returned bimap.

It is imperative that the user manually synchronize on the returned map when accessing any of its collection views:

  Bimap<K,V> m = Maps.synchronizedBiMap(
      new HashBiMap<K,V>());
   ...
  Set<K> s = m.keySet();  // Needn't be in synchronized block
   ...
  synchronized (m) {  // Synchronizing on m, not s!
    Iterator<K> i = s.iterator(); // Must be in synchronized block
    while (i.hasNext()) {
      foo(i.next());
    }
  }

Failure to follow this advice may result in non-deterministic behavior.

Parameters:

bimap - the bimap to be wrapped in a synchronized view

Returns:

a sychronized view of the specified bimap

uniqueIndex

public static <K,V> ImmutableMap<K,V> uniqueIndex(java.lang.Iterable<V> values,
                                                  Function<? super V,K> keyFunction)

Returns an immutable map for which the Map.values() are the given elements in the given order, and each key is the product of invoking a supplied function on its corresponding value.

Parameters:

values - the values to use when constructing the Map

keyFunction - the function used to produce the key for each value

Returns:

a map mapping the result of evaluating the function keyFunction on each value in the input collection to that value

Throws:

java.lang.IllegalArgumentException - if keyFunction produces the same key for more than one value in the input collection

java.lang.NullPointerException - if any elements of values is null, or if keyFunction produces null for any value

fromProperties

public static java.util.Map<java.lang.String,java.lang.String> fromProperties(java.util.Properties properties)

Creates a Map<String, String> from a Properties instance. Properties normally derive from Map<Object, Object>, but they typically contain strings, which is awkward. This method lets you get a plain-old-Map out of a Properties. The returned map won't include any null keys or values. The returned map is modifiable and serializable.

Parameters:

properties - a Properties object to be converted

Returns:

a map containing all the entries in properties

immutableEntry

public static <K,V> java.util.Map.Entry<K,V> immutableEntry(@Nullable
                                                            K key,
                                                            @Nullable
                                                            V value)

Returns an immutable map entry with the specified key and value. The Map.Entry.setValue(V) operation throws an UnsupportedOperationException.

The returned entry is serializable.

Parameters:

key - the key to be associated with the returned entry

value - the value to be associated with the returned entry

newHashBiMap

public static <K,V> HashBiMap<K,V> newHashBiMap()

Returns a new empty HashBiMap with the default initial capacity (16).

newEnumHashBiMap

public static <K extends java.lang.Enum<K>,V> EnumHashBiMap<K,V> newEnumHashBiMap(java.lang.Class<K> keyType)

Returns a new empty EnumHashBiMap using the specified key type.

Parameters:

keyType - the key type

newEnumBiMap

public static <K extends java.lang.Enum<K>,V extends java.lang.Enum<V>> EnumBiMap<K,V> newEnumBiMap(java.lang.Class<K> keyType,
                                                                                                    java.lang.Class<V> valueType)

Returns a new empty EnumBiMap using the specified key and value types.

Parameters:

keyType - the key type

valueType - the value type

unmodifiableBiMap

public static <K,V> BiMap<K,V> unmodifiableBiMap(BiMap<K,V> bimap)

Returns an unmodifiable view of the specified bimap. This method allows modules to provide users with "read-only" access to internal bimaps. Query operations on the returned bimap "read through" to the specified bimap, and attemps to modify the returned map, whether direct or via its collection views, result in an UnsupportedOperationException.

The returned bimap will be serializable if the specified bimap is serializable.

Parameters:

bimap - the bimap for which an unmodifiable view is to be returned

Returns:

an unmodifiable view of the specified bimap

newClassToInstanceMap

public static <B> ClassToInstanceMap<B> newClassToInstanceMap()

Returns a new ClassToInstanceMap instance backed by a HashMap using the default initial capacity and load factor.

newClassToInstanceMap

public static <B> ClassToInstanceMap<B> newClassToInstanceMap(java.util.Map<java.lang.Class<? extends B>,B> backingMap)

Returns a new ClassToInstanceMap instance backed by a given empty backingMap. The caller surrenders control of the backing map, and thus should not allow any direct references to it to remain accessible.