Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.google.common.collect
Class Maps

    java.lang.Object
      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, Isaac Shum

Method Summary
`static
`<K,V> MapDifference<K,V>`
` | `difference(Map<? extends K,? extends V> left, Map<? extends K,? extends V> right)` Computes the difference between two maps.
`static
`<K,V> Map<K,V>`
` | `filterEntries(Map<K,V> unfiltered, Predicate<? super Map.Entry<K,V>> entryPredicate)` Returns a map containing the mappings in `unfiltered` that satisfy a predicate.
`static
`<K,V> Map<K,V>`
` | `filterKeys(Map<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a map containing the mappings in `unfiltered` whose keys satisfy a predicate.
`static
`<K,V> Map<K,V>`
` | `filterValues(Map<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a map containing the mappings in `unfiltered` whose values satisfy a predicate.
`static ImmutableMap<String,String>` | `fromProperties(Properties properties)` Creates an `ImmutableMap<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
`<K extends Enum<K>,V> EnumMap<K,V>`
` | `newEnumMap(Class<K> type)` Creates an `EnumMap` instance.
`static
`<K extends Enum<K>,V> EnumMap<K,V>`
` | `newEnumMap(Map<K,? extends V> map)` Creates an `EnumMap` with the same mappings as the specified map.
`static
`<K,V> HashMap<K,V>`
` | `newHashMap()` Creates a mutable, empty `HashMap` instance.
`static
`<K,V> HashMap<K,V>`
` | `newHashMap(Map<? extends K,? extends V> map)` Creates a mutable `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 a mutable, empty, insertion-ordered `LinkedHashMap` instance.
`static
`<K,V> LinkedHashMap<K,V>`
` | `newLinkedHashMap(Map<? extends K,? extends V> map)` Creates a mutable, insertion-ordered `LinkedHashMap` instance with the same mappings as the specified map.
`static
`<K extends Comparable,V> TreeMap<K,V>`
` | `newTreeMap()` Creates a mutable, empty `TreeMap` instance using the natural ordering of its elements.
`static
`<C,K extends C,V> TreeMap<K,V>`
` | `newTreeMap(Comparator<C> comparator)` Creates a mutable, empty `TreeMap` instance using the given comparator.
`static
`<K,V> TreeMap<K,V>`
` | `newTreeMap(SortedMap<K,? extends V> map)` Creates a mutable `TreeMap` instance with the same mappings as the specified map and using the same ordering as the specified map.
`static
`<K,V> BiMap<K,V>`
` | `synchronizedBiMap(BiMap<K,V> bimap)` Returns a synchronized (thread-safe) bimap backed by the specified bimap.
`static
`<K,V1,V2> Map<K,V2>`
` | `transformValues(Map<K,V1> fromMap, Function<? super V1,V2> function)` Returns a view of a map where each value is transformed by a function.
`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<? extends K,? extends 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 mutable, empty `HashMap` instance.

  Note: if mutability is not required, use `ImmutableMap.of()` instead.

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

  Returns:
    a new, 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 new, empty `HashMap` 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 mutable `HashMap` instance with the same mappings as the specified map.

  Note: if mutability is not required, use `ImmutableMap.copyOf(Map)` instead.

  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 new `HashMap` initialized with the mappings from `map`

### newLinkedHashMap

    public static <K,V> LinkedHashMap<K,V> newLinkedHashMap()

  Creates a mutable, empty, insertion-ordered `LinkedHashMap` instance.

  Note: if mutability is not required, use `ImmutableMap.of()` instead.

  Returns:
    a new, empty `LinkedHashMap`

### newLinkedHashMap

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

  Creates a mutable, insertion-ordered `LinkedHashMap` instance with the same mappings as the specified map.

  Note: if mutability is not required, use `ImmutableMap.copyOf(Map)` instead.

  Parameters:
    `map` - the mappings to be placed in the new map
  Returns:
    a new, `LinkedHashMap` initialized with the mappings from `map`

### newTreeMap

    public static <K extends Comparable,V> TreeMap<K,V> newTreeMap()

  Creates a mutable, empty `TreeMap` instance using the natural ordering of its elements.

  Note: if mutability is not required, use `ImmutableSortedMap.of()` instead.

  Returns:
    a new, empty `TreeMap`

### newTreeMap

    public static <K,V> TreeMap<K,V> newTreeMap(SortedMap<K,? extends V> map)

  Creates a mutable `TreeMap` instance with the same mappings as the specified map and using the same ordering as the specified map.

  Note: if mutability is not required, use `ImmutableSortedMap.copyOfSorted(SortedMap)` instead.

  Parameters:
    `map` - the sorted map whose mappings are to be placed in the new map and whose comparator is to be used to sort the new map
  Returns:
    a new `TreeMap` initialized with the mappings from `map` and using the comparator of `map`

### newTreeMap

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

  Creates a mutable, empty `TreeMap` instance using the given comparator.

  Note: if mutability is not required, use `ImmutableSortedMap.orderedBy(comparator).build()` instead.

  Parameters:
    `comparator` - the comparator to sort the keys with
  Returns:
    a new, 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 new, empty `EnumMap`

### newEnumMap

    public static <K extends Enum<K>,V> EnumMap<K,V> newEnumMap(Map<K,? extends V> map)

  Creates an `EnumMap` with the same mappings as the specified map.

  Parameters:
    `map` - the map from which to initialize this `EnumMap`
  Returns:
    a new `EnumMap` initialized with the mappings from `map`
  Throws:
    `IllegalArgumentException` - if `m` is not an `EnumMap` instance and contains no mappings

### newIdentityHashMap

    public static <K,V> IdentityHashMap<K,V> newIdentityHashMap()

  Creates an `IdentityHashMap` instance.

  Returns:
    a new, empty `IdentityHashMap`

### 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<Long, String> map = Maps.synchronizedBiMap(
             HashBiMap.<Long, String>create());
          ...
         Set<Long> set = map.keySet();  // Needn't be in synchronized block
          ...
         synchronized (map) {  // Synchronizing on map, not set!
           Iterator<Long> it = set.iterator(); // Must be in synchronized block
           while (it.hasNext()) {
             foo(it.next());
           }
         }

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

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

  Parameters:
    `bimap` - the bimap to be wrapped in a synchronized view
  Returns:
    a sychronized view of the specified bimap

### difference

    public static <K,V> MapDifference<K,V> difference(Map<? extends K,? extends V> left,
                                                      Map<? extends K,? extends V> right)

  Computes the difference between two maps. This difference is an immutable snapshot of the state of the maps at the time this method is called. It will never change, even if the maps change at a later time.

  Since this method uses `HashMap` instances internally, the keys of the supplied maps must be well-behaved with respect to `Object.equals(java.lang.Object)` and `Object.hashCode()`.

  Note:If you only need to know whether two maps have the same mappings, call `left.equals(right)` instead of this method.

  Parameters:
    `left` - the map to treat as the "left" map for purposes of comparison
    `right` - the map to treat as the "right" map for purposes of comparison
  Returns:
    the difference between the two maps

### 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 ImmutableMap<String,String> fromProperties(Properties properties)

  Creates an `ImmutableMap<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`.

  Parameters:
    `properties` - a `Properties` object to be converted
  Returns:
    an immutable map containing all the entries in `properties`
  Throws:
    `ClassCastException` - if any key in `Properties` is not a `String`
    `NullPointerException` - if any key or value in `Properties` is null.

### 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

### unmodifiableBiMap

    public static <K,V> BiMap<K,V> unmodifiableBiMap(BiMap<? extends K,? extends 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

### transformValues

    public static <K,V1,V2> Map<K,V2> transformValues(Map<K,V1> fromMap,
                                                      Function<? super V1,V2> function)

  Returns a view of a map where each value is transformed by a function. All other properties of the map, such as iteration order, are left intact. For example, the code:

         Map<String, Integer> map = ImmutableMap.of("a", 4, "b", 9);
         Function<Integer, Double> sqrt = new Function<Integer, Double>() {
           public Double apply(Integer in) {
             return Math.sqrt((int) in);
           }
         };
         Map<String, Double> transformed = Maps.transformValues(sqrt, map);
         System.out.println(transformed);

  ... prints `{a=2.0, b=3.0}`.

  Changes in the underlying map are reflected in this view. Conversely, this view supports removal operations, and these are reflected in the underlying map.

  It's acceptable for the underlying map to contain null keys, and even null values provided that the function is capable of accepting null input. The transformed map might contain null values, if the function sometimes gives a null result.

  The returned map is not thread-safe or serializable, even if the underlying map is.

  The function is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the function will be applied many times for bulk operations like `Map.containsValue(java.lang.Object)` and `Map.toString()`. For this to perform well, `function` should be fast. To avoid lazy evaluation when the returned map doesn't need to be a view, copy the returned map into a new map of your choosing.

### filterKeys

    public static <K,V> Map<K,V> filterKeys(Map<K,V> unfiltered,
                                            Predicate<? super K> keyPredicate)

  Returns a map containing the mappings in `unfiltered` whose keys satisfy a predicate. The returned map is a live view of `unfiltered`; changes to one affect the other.

  The resulting map's `keySet()`, `entrySet()`, and `values()` views have iterators that don't support `remove()`, but all other methods are supported by the map and its views. The map's `put()` and `putAll()` methods throw an `IllegalArgumentException` if a key that doesn't satisfy the predicate is provided.

  When methods such as `removeAll()` and `clear()` are called on the filtered map or its views, only mappings whose keys satisfy the filter will be removed from the underlying map.

  The returned map isn't threadsafe or serializable, even if `unfiltered` is.

  Many of the filtered map's methods, such as `size()`, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.

### filterValues

    public static <K,V> Map<K,V> filterValues(Map<K,V> unfiltered,
                                              Predicate<? super V> valuePredicate)

  Returns a map containing the mappings in `unfiltered` whose values satisfy a predicate. The returned map is a live view of `unfiltered`; changes to one affect the other.

  The resulting map's `keySet()`, `entrySet()`, and `values()` views have iterators that don't support `remove()`, but all other methods are supported by the map and its views. The `Map.put(K, V)`, `Map.putAll(java.util.Map)`, and `Map.Entry.setValue(V)` methods throw an `IllegalArgumentException` if a value that doesn't satisfy the predicate is provided.

  When methods such as `removeAll()` and `clear()` are called on the filtered map or its views, only mappings whose values satisfy the filter will be removed from the underlying map.

  The returned map isn't threadsafe or serializable, even if `unfiltered` is.

  Many of the filtered map's methods, such as `size()`, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.

### filterEntries

    public static <K,V> Map<K,V> filterEntries(Map<K,V> unfiltered,
                                               Predicate<? super Map.Entry<K,V>> entryPredicate)

  Returns a map containing the mappings in `unfiltered` that satisfy a predicate. The returned map is a live view of `unfiltered`; changes to one affect the other.

  The resulting map's `keySet()`, `entrySet()`, and `values()` views have iterators that don't support `remove()`, but all other methods are supported by the map and its views. The map's `put()` and `putAll()` methods throw an `IllegalArgumentException` if a key/value pair that doesn't satisfy the predicate is provided. Similarly, the map's entries have a `Map.Entry.setValue(V)` method that throws an `IllegalArgumentException` when the existing key and the provided value don't satisfy the predicate.

  When methods such as `removeAll()` and `clear()` are called on the filtered map or its views, only mappings that satisfy the filter will be removed from the underlying map.

  The returned map isn't threadsafe or serializable, even if `unfiltered` is.

  Many of the filtered map's methods, such as `size()`, iterate across every key/value mapping in the underlying map and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered map and use the copy.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD