Maps
Date: 2016-05-24

com.google.common.collect

## Class Maps

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

-     @GwtCompatible(emulated=true)
      public final class Maps
      extends java.lang.Object

  Static utility methods pertaining to `Map` instances (including instances of `SortedMap`, `BiMap`, etc.). Also see this class's counterparts `Lists`, `Sets` and `Queues`.

  See the Guava User Guide article on `Maps`.

  Since:
    2.0

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `Maps.EntryTransformer<K,V1,V2>` A transformation of the value of a key-value pair, using both key and value as inputs.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <A,B> Converter<A,B>` | `asConverter(BiMap<A,B> bimap)` Returns a `Converter` that converts values using `bimap.get()`, and whose inverse view converts values using `bimap.inverse()``.get()`.
    `static <K,V> java.util.NavigableMap<K,V>` | `asMap(java.util.NavigableSet<K> set, Function<? super K,V> function)` Returns a view of the navigable set as a map, mapping keys from the set according to the specified function.
    `static <K,V> java.util.Map<K,V>` | `asMap(java.util.Set<K> set, Function<? super K,V> function)` Returns a live `Map` view whose keys are the contents of `set` and whose values are computed on demand using `function`.
    `static <K,V> java.util.SortedMap<K,V>` | `asMap(java.util.SortedSet<K> set, Function<? super K,V> function)` Returns a view of the sorted set as a map, mapping keys from the set according to the specified function.
    `static <K,V> MapDifference<K,V>` | `difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right)` Computes the difference between two maps.
    `static <K,V> MapDifference<K,V>` | `difference(java.util.Map<? extends K,? extends V> left, java.util.Map<? extends K,? extends V> right, Equivalence<? super V> valueEquivalence)` Computes the difference between two maps.
    `static <K,V> SortedMapDifference<K,V>` | `difference(java.util.SortedMap<K,? extends V> left, java.util.Map<? extends K,? extends V> right)` Computes the difference between two sorted maps, using the comparator of the left map, or `Ordering.natural()` if the left map uses the natural ordering of its elements.
    `static <K,V> BiMap<K,V>` | `filterEntries(BiMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a bimap containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> java.util.Map<K,V>` | `filterEntries(java.util.Map<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a map containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> java.util.NavigableMap<K,V>` | `filterEntries(java.util.NavigableMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a sorted map containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> java.util.SortedMap<K,V>` | `filterEntries(java.util.SortedMap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a sorted map containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> BiMap<K,V>` | `filterKeys(BiMap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a bimap containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> java.util.Map<K,V>` | `filterKeys(java.util.Map<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a map containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> java.util.NavigableMap<K,V>` | `filterKeys(java.util.NavigableMap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a navigable map containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> java.util.SortedMap<K,V>` | `filterKeys(java.util.SortedMap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a sorted map containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> BiMap<K,V>` | `filterValues(BiMap<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a bimap containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static <K,V> java.util.Map<K,V>` | `filterValues(java.util.Map<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a map containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static <K,V> java.util.NavigableMap<K,V>` | `filterValues(java.util.NavigableMap<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a navigable map containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static <K,V> java.util.SortedMap<K,V>` | `filterValues(java.util.SortedMap<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a sorted map containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static ImmutableMap<java.lang.String,java.lang.String>` | `fromProperties(java.util.Properties properties)` Creates an `ImmutableMap<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 <K extends java.lang.Enum<K>,V> ImmutableMap<K,V>` | `immutableEnumMap(java.util.Map<K,? extends V> map)` Returns an immutable map instance containing the given entries.
    `static <K,V> java.util.concurrent.ConcurrentMap<K,V>` | `newConcurrentMap()` Returns a general-purpose instance of `ConcurrentMap`, which supports all optional operations of the ConcurrentMap interface.
    `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 extends java.lang.Enum<K>,V> java.util.EnumMap<K,V>` | `newEnumMap(java.util.Map<K,? extends V> map)` Creates an `EnumMap` with the same mappings as the specified map.
    `static <K,V> java.util.HashMap<K,V>` | `newHashMap()` Creates a mutable, empty `HashMap` instance.
    `static <K,V> java.util.HashMap<K,V>` | `newHashMap(java.util.Map<? extends K,? extends V> map)` Creates a mutable `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 a high enough "initial capacity" that it should hold `expectedSize` elements without growth.
    `static <K,V> java.util.IdentityHashMap<K,V>` | `newIdentityHashMap()` Creates an `IdentityHashMap` instance.
    `static <K,V> java.util.LinkedHashMap<K,V>` | `newLinkedHashMap()` Creates a mutable, empty, insertion-ordered `LinkedHashMap` instance.
    `static <K,V> java.util.LinkedHashMap<K,V>` | `newLinkedHashMap(java.util.Map<? extends K,? extends V> map)` Creates a mutable, insertion-ordered `LinkedHashMap` instance with the same mappings as the specified map.
    `static <K,V> java.util.LinkedHashMap<K,V>` | `newLinkedHashMapWithExpectedSize(int expectedSize)` Creates a `LinkedHashMap` instance, with a high enough "initial capacity" that it should hold `expectedSize` elements without growth.
    `static <K extends java.lang.Comparable,V> java.util.TreeMap<K,V>` | `newTreeMap()` Creates a mutable, empty `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 mutable, empty `TreeMap` instance using the given comparator.
    `static <K,V> java.util.TreeMap<K,V>` | `newTreeMap(java.util.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,V> java.util.NavigableMap<K,V>` | `synchronizedNavigableMap(java.util.NavigableMap<K,V> navigableMap)` Returns a synchronized (thread-safe) navigable map backed by the specified navigable map.
    `static <K,V> ImmutableMap<K,V>` | `toMap(java.lang.Iterable<K> keys, Function<? super K,V> valueFunction)` Returns an immutable map whose keys are the distinct elements of `keys` and whose value for each key was computed by `valueFunction`.
    `static <K,V> ImmutableMap<K,V>` | `toMap(java.util.Iterator<K> keys, Function<? super K,V> valueFunction)` Returns an immutable map whose keys are the distinct elements of `keys` and whose value for each key was computed by `valueFunction`.
    `static <K,V1,V2> java.util.Map<K,V2>` | `transformEntries(java.util.Map<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)` Returns a view of a map whose values are derived from the original map's entries.
    `static <K,V1,V2> java.util.NavigableMap<K,V2>` | `transformEntries(java.util.NavigableMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)` Returns a view of a navigable map whose values are derived from the original navigable map's entries.
    `static <K,V1,V2> java.util.SortedMap<K,V2>` | `transformEntries(java.util.SortedMap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)` Returns a view of a sorted map whose values are derived from the original sorted map's entries.
    `static <K,V1,V2> java.util.Map<K,V2>` | `transformValues(java.util.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,V1,V2> java.util.NavigableMap<K,V2>` | `transformValues(java.util.NavigableMap<K,V1> fromMap, Function<? super V1,V2> function)` Returns a view of a navigable map where each value is transformed by a function.
    `static <K,V1,V2> java.util.SortedMap<K,V2>` | `transformValues(java.util.SortedMap<K,V1> fromMap, Function<? super V1,V2> function)` Returns a view of a sorted map where each value is transformed by a function.
    `static <K,V> ImmutableMap<K,V>` | `uniqueIndex(java.lang.Iterable<V> values, Function<? super V,K> keyFunction)` Returns a map with the given `values`, indexed by keys derived from those values.
    `static <K,V> ImmutableMap<K,V>` | `uniqueIndex(java.util.Iterator<V> values, Function<? super V,K> keyFunction)` Returns a map with the given `values`, indexed by keys derived from those values.
    `static <K,V> BiMap<K,V>` | `unmodifiableBiMap(BiMap<? extends K,? extends V> bimap)` Returns an unmodifiable view of the specified bimap.
    `static <K,V> java.util.NavigableMap<K,V>` | `unmodifiableNavigableMap(java.util.NavigableMap<K,V> map)` Returns an unmodifiable view of the specified navigable map.

    - ### Methods inherited from class java.lang.Object

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

- - ### Method Detail

    - #### immutableEnumMap

          @GwtCompatible(serializable=true)
          @Beta
          public static <K extends java.lang.Enum<K>,V> ImmutableMap<K,V> immutableEnumMap(java.util.Map<K,? extends V> map)

      Returns an immutable map instance containing the given entries. Internally, the returned map will be backed by an `EnumMap`.

      The iteration order of the returned map follows the enum's iteration order, not the order in which the elements appear in the given map.

      Parameters:
        `map` - the map to make an immutable copy of
      Returns:
        an immutable map containing those entries
      Since:
        14.0

    - #### newHashMap

          public static <K,V> java.util.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<K>)` instead.

      Returns:
        a new, empty `HashMap`

    - #### newHashMapWithExpectedSize

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

      Creates a `HashMap` instance, with a high enough "initial capacity" that it should hold `expectedSize` elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned map.
      Parameters:
        `expectedSize` - the number of entries you expect to add to the returned map
      Returns:
        a new, empty `HashMap` with enough capacity to hold `expectedSize` entries without resizing
      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 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<K>)` 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> java.util.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`

    - #### newLinkedHashMapWithExpectedSize

          public static <K,V> java.util.LinkedHashMap<K,V> newLinkedHashMapWithExpectedSize(int expectedSize)

      Creates a `LinkedHashMap` instance, with a high enough "initial capacity" that it should hold `expectedSize` elements without growth. This behavior cannot be broadly guaranteed, but it is observed to be true for OpenJDK 1.7. It also can't be guaranteed that the method isn't inadvertently oversizing the returned map.
      Parameters:
        `expectedSize` - the number of entries you expect to add to the returned map
      Returns:
        a new, empty `LinkedHashMap` with enough capacity to hold `expectedSize` entries without resizing
      Throws:
        `java.lang.IllegalArgumentException` - if `expectedSize` is negative
      Since:
        19.0

    - #### newLinkedHashMap

          public static <K,V> java.util.LinkedHashMap<K,V> newLinkedHashMap(java.util.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`

    - #### newConcurrentMap

          public static <K,V> java.util.concurrent.ConcurrentMap<K,V> newConcurrentMap()

      Returns a general-purpose instance of `ConcurrentMap`, which supports all optional operations of the ConcurrentMap interface. It does not permit null keys or values. It is serializable.

      This is currently accomplished by calling `MapMaker.makeMap()`.

      It is preferable to use `MapMaker` directly (rather than through this method), as it presents numerous useful configuration options, such as the concurrency level, load factor, key/value reference types, and value computation.

      Returns:
        a new, empty `ConcurrentMap`
      Since:
        3.0

    - #### newTreeMap

          public static <K extends java.lang.Comparable,V> java.util.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> java.util.TreeMap<K,V> newTreeMap(java.util.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> java.util.TreeMap<K,V> newTreeMap(@Nullable
                                                            java.util.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 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 new, empty `EnumMap`

    - #### newEnumMap

          public static <K extends java.lang.Enum<K>,V> java.util.EnumMap<K,V> newEnumMap(java.util.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:
        `java.lang.IllegalArgumentException` - if `m` is not an `EnumMap` instance and contains no mappings

    - #### newIdentityHashMap

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

      Creates an `IdentityHashMap` instance.
      Returns:
        a new, empty `IdentityHashMap`

    - #### difference

          public static <K,V> MapDifference<K,V> difference(java.util.Map<? extends K,? extends V> left,
                                            java.util.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

    - #### difference

          @Beta
          public static <K,V> MapDifference<K,V> difference(java.util.Map<? extends K,? extends V> left,
                                                 java.util.Map<? extends K,? extends V> right,
                                                 Equivalence<? super V> valueEquivalence)

      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.

      Values are compared using a provided equivalence, in the case of equality, the value on the 'left' is returned in the difference.

      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()`.

      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
        `valueEquivalence` - the equivalence relationship to use to compare values
      Returns:
        the difference between the two maps
      Since:
        10.0

    - #### difference

          public static <K,V> SortedMapDifference<K,V> difference(java.util.SortedMap<K,? extends V> left,
                                                  java.util.Map<? extends K,? extends V> right)

      Computes the difference between two sorted maps, using the comparator of the left map, or `Ordering.natural()` if the left map uses the natural ordering of its elements. 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 `TreeMap` instances internally, the keys of the right map must all compare as distinct according to the comparator of the left map.

      Note:If you only need to know whether two sorted 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
      Since:
        11.0

    - #### asMap

          public static <K,V> java.util.Map<K,V> asMap(java.util.Set<K> set,
                                       Function<? super K,V> function)

      Returns a live `Map` view whose keys are the contents of `set` and whose values are computed on demand using `function`. To get an immutable copy instead, use `toMap(Iterable, Function)`.

      Specifically, for each `k` in the backing set, the returned map has an entry mapping `k` to `function.apply(k)`. The `keySet`, `values`, and `entrySet` views of the returned map iterate in the same order as the backing set.

      Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.

      Warning: If the function rejects `null`, caution is required to make sure the set does not contain `null`, because the view cannot stop `null` from being added to the set.

      Warning: This method assumes that for any instance `k` of key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using a key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the resulting map view.

      Since:
        14.0

    - #### asMap

          public static <K,V> java.util.SortedMap<K,V> asMap(java.util.SortedSet<K> set,
                                             Function<? super K,V> function)

      Returns a view of the sorted set as a map, mapping keys from the set according to the specified function.

      Specifically, for each `k` in the backing set, the returned map has an entry mapping `k` to `function.apply(k)`. The `keySet`, `values`, and `entrySet` views of the returned map iterate in the same order as the backing set.

      Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.

      Warning: If the function rejects `null`, caution is required to make sure the set does not contain `null`, because the view cannot stop `null` from being added to the set.

      Warning: This method assumes that for any instance `k` of key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using a key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the resulting map view.

      Since:
        14.0

    - #### asMap

          @GwtIncompatible(value="NavigableMap")
          public static <K,V> java.util.NavigableMap<K,V> asMap(java.util.NavigableSet<K> set,
                                                                     Function<? super K,V> function)

      Returns a view of the navigable set as a map, mapping keys from the set according to the specified function.

      Specifically, for each `k` in the backing set, the returned map has an entry mapping `k` to `function.apply(k)`. The `keySet`, `values`, and `entrySet` views of the returned map iterate in the same order as the backing set.

      Modifications to the backing set are read through to the returned map. The returned map supports removal operations if the backing set does. Removal operations write through to the backing set. The returned map does not support put operations.

      Warning: If the function rejects `null`, caution is required to make sure the set does not contain `null`, because the view cannot stop `null` from being added to the set.

      Warning: This method assumes that for any instance `k` of key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using a key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the resulting map view.

      Since:
        14.0

    - #### toMap

          public static <K,V> ImmutableMap<K,V> toMap(java.lang.Iterable<K> keys,
                                      Function<? super K,V> valueFunction)

      Returns an immutable map whose keys are the distinct elements of `keys` and whose value for each key was computed by `valueFunction`. The map's iteration order is the order of the first appearance of each key in `keys`.

      When there are multiple instances of a key in `keys`, it is unspecified whether `valueFunction` will be applied to more than one instance of that key and, if it is, which result will be mapped to that key in the returned map.

      If `keys` is a `Set`, a live view can be obtained instead of a copy using `asMap(Set, Function)`.

      Throws:
        `java.lang.NullPointerException` - if any element of `keys` is `null`, or if `valueFunction` produces `null` for any key
      Since:
        14.0

    - #### toMap

          public static <K,V> ImmutableMap<K,V> toMap(java.util.Iterator<K> keys,
                                      Function<? super K,V> valueFunction)

      Returns an immutable map whose keys are the distinct elements of `keys` and whose value for each key was computed by `valueFunction`. The map's iteration order is the order of the first appearance of each key in `keys`.

      When there are multiple instances of a key in `keys`, it is unspecified whether `valueFunction` will be applied to more than one instance of that key and, if it is, which result will be mapped to that key in the returned map.

      Throws:
        `java.lang.NullPointerException` - if any element of `keys` is `null`, or if `valueFunction` produces `null` for any key
      Since:
        14.0

    - #### uniqueIndex

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

      Returns a map with the given `values`, indexed by keys derived from those values. In other words, each input value produces an entry in the map whose key is the result of applying `keyFunction` to that value. These entries appear in the same order as the input values. Example usage:

             Color red = new Color("red", 255, 0, 0);
             ...
             ImmutableSet<Color> allColors = ImmutableSet.of(red, green, blue);

             Map<String, Color> colorForName =
                 uniqueIndex(allColors, toStringFunction());
             assertThat(colorForName).containsEntry("red", red);

      If your index may associate multiple values with each key, use `Multimaps.index`.

      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

    - #### uniqueIndex

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

      Returns a map with the given `values`, indexed by keys derived from those values. In other words, each input value produces an entry in the map whose key is the result of applying `keyFunction` to that value. These entries appear in the same order as the input values. Example usage:

             Color red = new Color("red", 255, 0, 0);
             ...
             Iterator<Color> allColors = ImmutableSet.of(red, green, blue).iterator();

             Map<String, Color> colorForName =
                 uniqueIndex(allColors, toStringFunction());
             assertThat(colorForName).containsEntry("red", red);

      If your index may associate multiple values with each key, use `Multimaps.index`.

      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
      Since:
        10.0

    - #### fromProperties

          @GwtIncompatible(value="java.util.Properties")
          public static ImmutableMap<java.lang.String,java.lang.String> fromProperties(java.util.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:
        `java.lang.ClassCastException` - if any key in `Properties` is not a `String`
        `java.lang.NullPointerException` - if any key or value in `Properties` is null

    - #### immutableEntry

          @GwtCompatible(serializable=true)
          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

    - #### asConverter

          @Beta
          public static <A,B> Converter<A,B> asConverter(BiMap<A,B> bimap)

      Returns a `Converter` that converts values using `bimap.get()`, and whose inverse view converts values using `bimap.inverse()``.get()`.

      To use a plain `Map` as a `Function`, see `Functions.forMap(Map)` or `Functions.forMap(Map, Object)`.

      Since:
        16.0

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

    - #### 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 attempts 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> java.util.Map<K,V2> transformValues(java.util.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(map, sqrt);
             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.

    - #### transformValues

          public static <K,V1,V2> java.util.SortedMap<K,V2> transformValues(java.util.SortedMap<K,V1> fromMap,
                                                            Function<? super V1,V2> function)

      Returns a view of a sorted 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:

             SortedMap<String, Integer> map = ImmutableSortedMap.of("a", 4, "b", 9);
             Function<Integer, Double> sqrt =
                 new Function<Integer, Double>() {
                   public Double apply(Integer in) {
                     return Math.sqrt((int) in);
                   }
                 };
             SortedMap<String, Double> transformed =
                  Maps.transformValues(map, sqrt);
             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.

      Since:
        11.0

    - #### transformValues

          @GwtIncompatible(value="NavigableMap")
          public static <K,V1,V2> java.util.NavigableMap<K,V2> transformValues(java.util.NavigableMap<K,V1> fromMap,
                                                                                    Function<? super V1,V2> function)

      Returns a view of a navigable 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:

             NavigableMap<String, Integer> map = Maps.newTreeMap();
             map.put("a", 4);
             map.put("b", 9);
             Function<Integer, Double> sqrt =
                 new Function<Integer, Double>() {
                   public Double apply(Integer in) {
                     return Math.sqrt((int) in);
                   }
                 };
             NavigableMap<String, Double> transformed =
                  Maps.transformNavigableValues(map, sqrt);
             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.

      Since:
        13.0

    - #### transformEntries

          public static <K,V1,V2> java.util.Map<K,V2> transformEntries(java.util.Map<K,V1> fromMap,
                                                       Maps.EntryTransformer<? super K,? super V1,V2> transformer)

      Returns a view of a map whose values are derived from the original map's entries. In contrast to `transformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)`, this method's entry-transformation logic may depend on the key as well as the value.

      All other properties of the transformed map, such as iteration order, are left intact. For example, the code:

             Map<String, Boolean> options =
                 ImmutableMap.of("verbose", true, "sort", false);
             EntryTransformer<String, Boolean, String> flagPrefixer =
                 new EntryTransformer<String, Boolean, String>() {
                   public String transformEntry(String key, Boolean value) {
                     return value ? key : "no" + key;
                   }
                 };
             Map<String, String> transformed =
                 Maps.transformEntries(options, flagPrefixer);
             System.out.println(transformed);

      ... prints `{verbose=verbose, sort=nosort}`.

      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 null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.

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

      The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like `Map.containsValue(java.lang.Object)` and `Object.toString()`. For this to perform well, `transformer` 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.

      Warning: This method assumes that for any instance `k` of `EntryTransformer` key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using an `EntryTransformer` key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the transformed map.

      Since:
        7.0

    - #### transformEntries

          public static <K,V1,V2> java.util.SortedMap<K,V2> transformEntries(java.util.SortedMap<K,V1> fromMap,
                                                             Maps.EntryTransformer<? super K,? super V1,V2> transformer)

      Returns a view of a sorted map whose values are derived from the original sorted map's entries. In contrast to `transformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)`, this method's entry-transformation logic may depend on the key as well as the value.

      All other properties of the transformed map, such as iteration order, are left intact. For example, the code:

             Map<String, Boolean> options =
                 ImmutableSortedMap.of("verbose", true, "sort", false);
             EntryTransformer<String, Boolean, String> flagPrefixer =
                 new EntryTransformer<String, Boolean, String>() {
                   public String transformEntry(String key, Boolean value) {
                     return value ? key : "yes" + key;
                   }
                 };
             SortedMap<String, String> transformed =
                 Maps.transformEntries(options, flagPrefixer);
             System.out.println(transformed);

      ... prints `{sort=yessort, verbose=verbose}`.

      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 null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.

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

      The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like `Map.containsValue(java.lang.Object)` and `Object.toString()`. For this to perform well, `transformer` 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.

      Warning: This method assumes that for any instance `k` of `EntryTransformer` key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using an `EntryTransformer` key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the transformed map.

      Since:
        11.0

    - #### transformEntries

          @GwtIncompatible(value="NavigableMap")
          public static <K,V1,V2> java.util.NavigableMap<K,V2> transformEntries(java.util.NavigableMap<K,V1> fromMap,
                                                                                     Maps.EntryTransformer<? super K,? super V1,V2> transformer)

      Returns a view of a navigable map whose values are derived from the original navigable map's entries. In contrast to `transformValues(java.util.Map<K, V1>, com.google.common.base.Function<? super V1, V2>)`, this method's entry-transformation logic may depend on the key as well as the value.

      All other properties of the transformed map, such as iteration order, are left intact. For example, the code:

             NavigableMap<String, Boolean> options = Maps.newTreeMap();
             options.put("verbose", false);
             options.put("sort", true);
             EntryTransformer<String, Boolean, String> flagPrefixer =
                 new EntryTransformer<String, Boolean, String>() {
                   public String transformEntry(String key, Boolean value) {
                     return value ? key : ("yes" + key);
                   }
                 };
             NavigableMap<String, String> transformed =
                 LabsMaps.transformNavigableEntries(options, flagPrefixer);
             System.out.println(transformed);

      ... prints `{sort=yessort, verbose=verbose}`.

      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 null values provided that the transformer is capable of accepting null inputs. The transformed map might contain null values if the transformer sometimes gives a null result.

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

      The transformer is applied lazily, invoked when needed. This is necessary for the returned map to be a view, but it means that the transformer will be applied many times for bulk operations like `Map.containsValue(java.lang.Object)` and `Object.toString()`. For this to perform well, `transformer` 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.

      Warning: This method assumes that for any instance `k` of `EntryTransformer` key type `K`, `k.equals(k2)` implies that `k2` is also of type `K`. Using an `EntryTransformer` key type for which this may not hold, such as `ArrayList`, may risk a `ClassCastException` when calling methods on the transformed map.

      Since:
        13.0

    - #### filterKeys

          @CheckReturnValue
          public static <K,V> java.util.Map<K,V> filterKeys(java.util.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. When given a key that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`.

      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.

      Warning: `keyPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

    - #### filterKeys

          @CheckReturnValue
          public static <K,V> java.util.SortedMap<K,V> filterKeys(java.util.SortedMap<K,V> unfiltered,
                                                                   Predicate<? super K> keyPredicate)

      Returns a sorted 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. When given a key that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`.

      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.

      Warning: `keyPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

      Since:
        11.0

    - #### filterKeys

          @GwtIncompatible(value="NavigableMap")
          @CheckReturnValue
          public static <K,V> java.util.NavigableMap<K,V> filterKeys(java.util.NavigableMap<K,V> unfiltered,
                                                                                           Predicate<? super K> keyPredicate)

      Returns a navigable 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. When given a key that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`.

      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.

      Warning: `keyPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

      Since:
        14.0

    - #### filterKeys

          @CheckReturnValue
          public static <K,V> BiMap<K,V> filterKeys(BiMap<K,V> unfiltered,
                                                     Predicate<? super K> keyPredicate)

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

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

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

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

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

      Warning: `entryPredicate` must be consistent with equals , as documented at `Predicate.apply(T)`.

      Since:
        14.0

    - #### filterValues

          @CheckReturnValue
          public static <K,V> java.util.Map<K,V> filterValues(java.util.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. When given a value that doesn't satisfy the predicate, the map's `put()`, `putAll()`, and `Map.Entry.setValue(V)` methods throw an `IllegalArgumentException`.

      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.

      Warning: `valuePredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

    - #### filterValues

          @CheckReturnValue
          public static <K,V> java.util.SortedMap<K,V> filterValues(java.util.SortedMap<K,V> unfiltered,
                                                                     Predicate<? super V> valuePredicate)

      Returns a sorted 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. When given a value that doesn't satisfy the predicate, the map's `put()`, `putAll()`, and `Map.Entry.setValue(V)` methods throw an `IllegalArgumentException`.

      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.

      Warning: `valuePredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

      Since:
        11.0

    - #### filterValues

          @GwtIncompatible(value="NavigableMap")
          @CheckReturnValue
          public static <K,V> java.util.NavigableMap<K,V> filterValues(java.util.NavigableMap<K,V> unfiltered,
                                                                                             Predicate<? super V> valuePredicate)

      Returns a navigable 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. When given a value that doesn't satisfy the predicate, the map's `put()`, `putAll()`, and `Map.Entry.setValue(V)` methods throw an `IllegalArgumentException`.

      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.

      Warning: `valuePredicate` must be consistent with equals, as documented at `Predicate.apply(T)`. Do not provide a predicate such as `Predicates.instanceOf(ArrayList.class)`, which is inconsistent with equals.

      Since:
        14.0

    - #### filterValues

          @CheckReturnValue
          public static <K,V> BiMap<K,V> filterValues(BiMap<K,V> unfiltered,
                                                       Predicate<? super V> valuePredicate)

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

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

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

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

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

      Warning: `entryPredicate` must be consistent with equals , as documented at `Predicate.apply(T)`.

      Since:
        14.0

    - #### filterEntries

          @CheckReturnValue
          public static <K,V> java.util.Map<K,V> filterEntries(java.util.Map<K,V> unfiltered,
                                                                Predicate<? super java.util.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. When given a key/value pair that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`. 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.

      Warning: `entryPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`.

    - #### filterEntries

          @CheckReturnValue
          public static <K,V> java.util.SortedMap<K,V> filterEntries(java.util.SortedMap<K,V> unfiltered,
                                                                      Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)

      Returns a sorted 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. When given a key/value pair that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`. 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.

      Warning: `entryPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`.

      Since:
        11.0

    - #### filterEntries

          @GwtIncompatible(value="NavigableMap")
          @CheckReturnValue
          public static <K,V> java.util.NavigableMap<K,V> filterEntries(java.util.NavigableMap<K,V> unfiltered,
                                                                                              Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)

      Returns a sorted 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. When given a key/value pair that doesn't satisfy the predicate, the map's `put()` and `putAll()` methods throw an `IllegalArgumentException`. 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.

      Warning: `entryPredicate` must be consistent with equals, as documented at `Predicate.apply(T)`.

      Since:
        14.0

    - #### filterEntries

          @CheckReturnValue
          public static <K,V> BiMap<K,V> filterEntries(BiMap<K,V> unfiltered,
                                                        Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)

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

      The resulting bimap's `keySet()`, `entrySet()`, and `values()` views have iterators that don't support `remove()`, but all other methods are supported by the bimap and its views. When given a key/value pair that doesn't satisfy the predicate, the bimap's `put()`, `forcePut()` and `putAll()` methods throw an `IllegalArgumentException`. Similarly, the map's entries have an `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 bimap or its views, only mappings that satisfy the filter will be removed from the underlying bimap.

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

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

      Warning: `entryPredicate` must be consistent with equals , as documented at `Predicate.apply(T)`.

      Since:
        14.0

    - #### unmodifiableNavigableMap

          @GwtIncompatible(value="NavigableMap")
          public static <K,V> java.util.NavigableMap<K,V> unmodifiableNavigableMap(java.util.NavigableMap<K,V> map)

      Returns an unmodifiable view of the specified navigable map. Query operations on the returned map read through to the specified map, and attempts to modify the returned map, whether direct or via its views, result in an `UnsupportedOperationException`.

      The returned navigable map will be serializable if the specified navigable map is serializable.

      Parameters:
        `map` - the navigable map for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified navigable map
      Since:
        12.0

    - #### synchronizedNavigableMap

          @GwtIncompatible(value="NavigableMap")
          public static <K,V> java.util.NavigableMap<K,V> synchronizedNavigableMap(java.util.NavigableMap<K,V> navigableMap)

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

      It is imperative that the user manually synchronize on the returned navigable map when iterating over any of its collection views, or the collections views of any of its `descendingMap`, `subMap`, `headMap` or `tailMap` views.

             NavigableMap<K, V> map = synchronizedNavigableMap(new TreeMap<K, V>());

             // Needn't be in synchronized block
             NavigableSet<K> set = map.navigableKeySet();

             synchronized (map) { // Synchronizing on map, not set!
               Iterator<K> it = set.iterator(); // Must be in synchronized block
               while (it.hasNext()) {
                 foo(it.next());
               }
             }

      or:

             NavigableMap<K, V> map = synchronizedNavigableMap(new TreeMap<K, V>());
             NavigableMap<K, V> map2 = map.subMap(foo, false, bar, true);

             // Needn't be in synchronized block
             NavigableSet<K> set2 = map2.descendingKeySet();

             synchronized (map) { // Synchronizing on map, not map2 or set2!
               Iterator<K> it = set2.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 navigable map will be serializable if the specified navigable map is serializable.

      Parameters:
        `navigableMap` - the navigable map to be "wrapped" in a synchronized navigable map.
      Returns:
        a synchronized view of the specified navigable map.
      Since:
        13.0