com.google.common.collect
Class Maps

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

public final class Maps
extends 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(Map<?,?> map, Object key, Object value)
          Returns true if map contains an entry mapping key to value.
static Map<String,String> fromProperties(Properties properties)
          Creates a Map<String, String> from a Properties instance.
static
<K,V> 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(Map<Class<? extends B>,B> backingMap)
          Returns a new ClassToInstanceMap instance backed by a given empty backingMap.
static
<K,V> ConcurrentHashMap<K,V>
newConcurrentHashMap()
          Creates a ConcurrentHashMap instance.
static
<K extends Enum<K>,V extends Enum<V>>
EnumBiMap<K,V>
newEnumBiMap(Class<K> keyType, Class<V> valueType)
          Returns a new empty EnumBiMap using the specified key and value types.
static
<K extends Enum<K>,V>
EnumHashBiMap<K,V>
newEnumHashBiMap(Class<K> keyType)
          Returns a new empty EnumHashBiMap using the specified key type.
static
<K extends Enum<K>,V>
EnumMap<K,V>
newEnumMap(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> HashMap<K,V>
newHashMap()
          Creates a HashMap instance.
static
<K,V> HashMap<K,V>
newHashMap(Map<? extends K,? extends V> map)
          Creates a HashMap instance with the same mappings as the specified map.
static
<K,V> 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> IdentityHashMap<K,V>
newIdentityHashMap()
          Creates an IdentityHashMap instance.
static
<K,V> LinkedHashMap<K,V>
newLinkedHashMap()
          Creates an insertion-ordered LinkedHashMap instance.
static
<K,V> LinkedHashMap<K,V>
newLinkedHashMap(Map<? extends K,? extends V> map)
          Creates an insertion-ordered LinkedHashMap instance with the same mappings as the specified map.
static
<K extends Comparable,V>
TreeMap<K,V>
newTreeMap()
          Creates a TreeMap instance using the natural ordering of its elements.
static
<C,K extends C,V>
TreeMap<K,V>
newTreeMap(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(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> 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> 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:
IllegalArgumentException - if expectedSize is negative

newHashMap

public static <K,V> HashMap<K,V> newHashMap(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> LinkedHashMap<K,V> newLinkedHashMap()
Creates an insertion-ordered LinkedHashMap instance.

Returns:
a newly-created, initially-empty LinkedHashMap

newLinkedHashMap

public static <K,V> LinkedHashMap<K,V> newLinkedHashMap(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> ConcurrentHashMap<K,V> newConcurrentHashMap()
Creates a ConcurrentHashMap instance.

Returns:
a newly-created, initially-empty ConcurrentHashMap

newTreeMap

public static <K extends Comparable,V> 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> TreeMap<K,V> newTreeMap(@Nullable
                                                        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 Enum<K>,V> EnumMap<K,V> newEnumMap(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> IdentityHashMap<K,V> newIdentityHashMap()
Creates an IdentityHashMap instance.

Returns:
a newly-created, initially-empty IdentityHashMap

containsEntry

public static boolean containsEntry(Map<?,?> map,
                                    @Nullable
                                    Object key,
                                    @Nullable
                                    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(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:
IllegalArgumentException - if keyFunction produces the same key for more than one value in the input collection
NullPointerException - if any elements of values is null, or if keyFunction produces null for any value

fromProperties

public static Map<String,String> fromProperties(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> 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 Enum<K>,V> EnumHashBiMap<K,V> newEnumHashBiMap(Class<K> keyType)
Returns a new empty EnumHashBiMap using the specified key type.

Parameters:
keyType - the key type

newEnumBiMap

public static <K extends Enum<K>,V extends Enum<V>> EnumBiMap<K,V> newEnumBiMap(Class<K> keyType,
                                                                                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(Map<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.