Multimaps
Date: 2016-05-24

com.google.common.collect

## Class Multimaps

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

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

  Provides static methods acting on or generating a `Multimap`.

  See the Guava User Guide article on `Multimaps`.

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static <K,V> java.util.Map<K,java.util.List<V>>` | `asMap(ListMultimap<K,V> multimap)` Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, List<V>>`.
    `static <K,V> java.util.Map<K,java.util.Collection<V>>` | `asMap(Multimap<K,V> multimap)` Returns `multimap.asMap()`.
    `static <K,V> java.util.Map<K,java.util.Set<V>>` | `asMap(SetMultimap<K,V> multimap)` Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, Set<V>>`.
    `static <K,V> java.util.Map<K,java.util.SortedSet<V>>` | `asMap(SortedSetMultimap<K,V> multimap)` Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, SortedSet<V>>`.
    `static <K,V> Multimap<K,V>` | `filterEntries(Multimap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a multimap containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> SetMultimap<K,V>` | `filterEntries(SetMultimap<K,V> unfiltered, Predicate<? super java.util.Map.Entry<K,V>> entryPredicate)` Returns a multimap containing the mappings in `unfiltered` that satisfy a predicate.
    `static <K,V> ListMultimap<K,V>` | `filterKeys(ListMultimap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a multimap containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> Multimap<K,V>` | `filterKeys(Multimap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a multimap containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> SetMultimap<K,V>` | `filterKeys(SetMultimap<K,V> unfiltered, Predicate<? super K> keyPredicate)` Returns a multimap containing the mappings in `unfiltered` whose keys satisfy a predicate.
    `static <K,V> Multimap<K,V>` | `filterValues(Multimap<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a multimap containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static <K,V> SetMultimap<K,V>` | `filterValues(SetMultimap<K,V> unfiltered, Predicate<? super V> valuePredicate)` Returns a multimap containing the mappings in `unfiltered` whose values satisfy a predicate.
    `static <K,V> SetMultimap<K,V>` | `forMap(java.util.Map<K,V> map)` Returns a multimap view of the specified map.
    `static <K,V> ImmutableListMultimap<K,V>` | `index(java.lang.Iterable<V> values, Function<? super V,K> keyFunction)` Creates an index `ImmutableListMultimap` that contains the results of applying a specified function to each item in an `Iterable` of values.
    `static <K,V> ImmutableListMultimap<K,V>` | `index(java.util.Iterator<V> values, Function<? super V,K> keyFunction)` Creates an index `ImmutableListMultimap` that contains the results of applying a specified function to each item in an `Iterator` of values.
    `static <K,V,M extends Multimap<K,V>> M` | `invertFrom(Multimap<? extends V,? extends K> source, M dest)` Copies each key-value mapping in `source` into `dest`, with its key and value reversed.
    `static <K,V> ListMultimap<K,V>` | `newListMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.List<V>> factory)` Creates a new `ListMultimap` that uses the provided map and factory.
    `static <K,V> Multimap<K,V>` | `newMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.Collection<V>> factory)` Creates a new `Multimap` backed by `map`, whose internal value collections are generated by `factory`.
    `static <K,V> SetMultimap<K,V>` | `newSetMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.Set<V>> factory)` Creates a new `SetMultimap` that uses the provided map and factory.
    `static <K,V> SortedSetMultimap<K,V>` | `newSortedSetMultimap(java.util.Map<K,java.util.Collection<V>> map, Supplier<? extends java.util.SortedSet<V>> factory)` Creates a new `SortedSetMultimap` that uses the provided map and factory.
    `static <K,V> ListMultimap<K,V>` | `synchronizedListMultimap(ListMultimap<K,V> multimap)` Returns a synchronized (thread-safe) `ListMultimap` backed by the specified multimap.
    `static <K,V> Multimap<K,V>` | `synchronizedMultimap(Multimap<K,V> multimap)` Returns a synchronized (thread-safe) multimap backed by the specified multimap.
    `static <K,V> SetMultimap<K,V>` | `synchronizedSetMultimap(SetMultimap<K,V> multimap)` Returns a synchronized (thread-safe) `SetMultimap` backed by the specified multimap.
    `static <K,V> SortedSetMultimap<K,V>` | `synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap)` Returns a synchronized (thread-safe) `SortedSetMultimap` backed by the specified multimap.
    `static <K,V1,V2> ListMultimap<K,V2>` | `transformEntries(ListMultimap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)` Returns a view of a `ListMultimap` whose values are derived from the original multimap's entries.
    `static <K,V1,V2> Multimap<K,V2>` | `transformEntries(Multimap<K,V1> fromMap, Maps.EntryTransformer<? super K,? super V1,V2> transformer)` Returns a view of a multimap whose values are derived from the original multimap's entries.
    `static <K,V1,V2> ListMultimap<K,V2>` | `transformValues(ListMultimap<K,V1> fromMultimap, Function<? super V1,V2> function)` Returns a view of a `ListMultimap` where each value is transformed by a function.
    `static <K,V1,V2> Multimap<K,V2>` | `transformValues(Multimap<K,V1> fromMultimap, Function<? super V1,V2> function)` Returns a view of a multimap where each value is transformed by a function.
    `static <K,V> ListMultimap<K,V>` | `unmodifiableListMultimap(ImmutableListMultimap<K,V> delegate)` Deprecated. no need to use this
    `static <K,V> ListMultimap<K,V>` | `unmodifiableListMultimap(ListMultimap<K,V> delegate)` Returns an unmodifiable view of the specified `ListMultimap`.
    `static <K,V> Multimap<K,V>` | `unmodifiableMultimap(ImmutableMultimap<K,V> delegate)` Deprecated. no need to use this
    `static <K,V> Multimap<K,V>` | `unmodifiableMultimap(Multimap<K,V> delegate)` Returns an unmodifiable view of the specified multimap.
    `static <K,V> SetMultimap<K,V>` | `unmodifiableSetMultimap(ImmutableSetMultimap<K,V> delegate)` Deprecated. no need to use this
    `static <K,V> SetMultimap<K,V>` | `unmodifiableSetMultimap(SetMultimap<K,V> delegate)` Returns an unmodifiable view of the specified `SetMultimap`.
    `static <K,V> SortedSetMultimap<K,V>` | `unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate)` Returns an unmodifiable view of the specified `SortedSetMultimap`.

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

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

- - ### Method Detail

    - #### newMultimap

          public static <K,V> Multimap<K,V> newMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                        Supplier<? extends java.util.Collection<V>> factory)

      Creates a new `Multimap` backed by `map`, whose internal value collections are generated by `factory`. Warning: do not use this method when the collections returned by `factory` implement either `List` or `Set`! Use the more specific method `newListMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.List<V>>)`, `newSetMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.Set<V>>)` or `newSortedSetMultimap(java.util.Map<K, java.util.Collection<V>>, com.google.common.base.Supplier<? extends java.util.SortedSet<V>>)` instead, to avoid very surprising behavior from `Multimap.equals(java.lang.Object)`.

      The `factory`-generated and `map` classes determine the multimap iteration order. They also specify the behavior of the `equals`, `hashCode`, and `toString` methods for the multimap and its returned views. However, the multimap's `get` method returns instances of a different class than `factory.get()` does.

      The multimap is serializable if `map`, `factory`, the collections generated by `factory`, and the multimap contents are all serializable.

      The multimap is not threadsafe when any concurrent operations update the multimap, even if `map` and the instances generated by `factory` are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to `synchronizedMultimap(com.google.common.collect.Multimap<K, V>)`.

      Call this method only when the simpler methods `ArrayListMultimap.create()`, `HashMultimap.create()`, `LinkedHashMultimap.create()`, `LinkedListMultimap.create()`, `TreeMultimap.create()`, and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

      Note: the multimap assumes complete ownership over of `map` and the collections returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

      Parameters:
        `map` - place to store the mapping from each key to its corresponding values
        `factory` - supplier of new, empty collections that will each hold all values for a given key
      Throws:
        `java.lang.IllegalArgumentException` - if `map` is not empty

    - #### newListMultimap

          public static <K,V> ListMultimap<K,V> newListMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                                Supplier<? extends java.util.List<V>> factory)

      Creates a new `ListMultimap` that uses the provided map and factory. It can generate a multimap based on arbitrary `Map` and `List` classes.

      The `factory`-generated and `map` classes determine the multimap iteration order. They also specify the behavior of the `equals`, `hashCode`, and `toString` methods for the multimap and its returned views. The multimap's `get`, `removeAll`, and `replaceValues` methods return `RandomAccess` lists if the factory does. However, the multimap's `get` method returns instances of a different class than does `factory.get()`.

      The multimap is serializable if `map`, `factory`, the lists generated by `factory`, and the multimap contents are all serializable.

      The multimap is not threadsafe when any concurrent operations update the multimap, even if `map` and the instances generated by `factory` are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to `synchronizedListMultimap(com.google.common.collect.ListMultimap<K, V>)`.

      Call this method only when the simpler methods `ArrayListMultimap.create()` and `LinkedListMultimap.create()` won't suffice.

      Note: the multimap assumes complete ownership over of `map` and the lists returned by `factory`. Those objects should not be manually updated, they should be empty when provided, and they should not use soft, weak, or phantom references.

      Parameters:
        `map` - place to store the mapping from each key to its corresponding values
        `factory` - supplier of new, empty lists that will each hold all values for a given key
      Throws:
        `java.lang.IllegalArgumentException` - if `map` is not empty

    - #### newSetMultimap

          public static <K,V> SetMultimap<K,V> newSetMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                              Supplier<? extends java.util.Set<V>> factory)

      Creates a new `SetMultimap` that uses the provided map and factory. It can generate a multimap based on arbitrary `Map` and `Set` classes.

      The `factory`-generated and `map` classes determine the multimap iteration order. They also specify the behavior of the `equals`, `hashCode`, and `toString` methods for the multimap and its returned views. However, the multimap's `get` method returns instances of a different class than `factory.get()` does.

      The multimap is serializable if `map`, `factory`, the sets generated by `factory`, and the multimap contents are all serializable.

      The multimap is not threadsafe when any concurrent operations update the multimap, even if `map` and the instances generated by `factory` are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to `synchronizedSetMultimap(com.google.common.collect.SetMultimap<K, V>)`.

      Call this method only when the simpler methods `HashMultimap.create()`, `LinkedHashMultimap.create()`, `TreeMultimap.create()`, and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

      Note: the multimap assumes complete ownership over of `map` and the sets returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

      Parameters:
        `map` - place to store the mapping from each key to its corresponding values
        `factory` - supplier of new, empty sets that will each hold all values for a given key
      Throws:
        `java.lang.IllegalArgumentException` - if `map` is not empty

    - #### newSortedSetMultimap

          public static <K,V> SortedSetMultimap<K,V> newSortedSetMultimap(java.util.Map<K,java.util.Collection<V>> map,
                                                          Supplier<? extends java.util.SortedSet<V>> factory)

      Creates a new `SortedSetMultimap` that uses the provided map and factory. It can generate a multimap based on arbitrary `Map` and `SortedSet` classes.

      The `factory`-generated and `map` classes determine the multimap iteration order. They also specify the behavior of the `equals`, `hashCode`, and `toString` methods for the multimap and its returned views. However, the multimap's `get` method returns instances of a different class than `factory.get()` does.

      The multimap is serializable if `map`, `factory`, the sets generated by `factory`, and the multimap contents are all serializable.

      The multimap is not threadsafe when any concurrent operations update the multimap, even if `map` and the instances generated by `factory` are. Concurrent read operations will work correctly. To allow concurrent update operations, wrap the multimap with a call to `synchronizedSortedSetMultimap(com.google.common.collect.SortedSetMultimap<K, V>)`.

      Call this method only when the simpler methods `TreeMultimap.create()` and `TreeMultimap.create(Comparator, Comparator)` won't suffice.

      Note: the multimap assumes complete ownership over of `map` and the sets returned by `factory`. Those objects should not be manually updated and they should not use soft, weak, or phantom references.

      Parameters:
        `map` - place to store the mapping from each key to its corresponding values
        `factory` - supplier of new, empty sorted sets that will each hold all values for a given key
      Throws:
        `java.lang.IllegalArgumentException` - if `map` is not empty

    - #### invertFrom

          public static <K,V,M extends Multimap<K,V>> M invertFrom(Multimap<? extends V,? extends K> source,
                                                   M dest)

      Copies each key-value mapping in `source` into `dest`, with its key and value reversed.

      If `source` is an `ImmutableMultimap`, consider using `ImmutableMultimap.inverse()` instead.

      Parameters:
        `source` - any multimap
        `dest` - the multimap to copy into; usually empty
      Returns:
        `dest`

    - #### synchronizedMultimap

          public static <K,V> Multimap<K,V> synchronizedMultimap(Multimap<K,V> multimap)

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

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

             Multimap<K, V> multimap = Multimaps.synchronizedMultimap(
                 HashMultimap.<K, V>create());
             ...
             Collection<V> values = multimap.get(key);  // Needn't be in synchronized block
             ...
             synchronized (multimap) {  // Synchronizing on multimap, not values!
               Iterator<V> i = values.iterator(); // Must be in synchronized block
               while (i.hasNext()) {
                 foo(i.next());
               }
             }

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

      Note that the generated multimap's `Multimap.removeAll(java.lang.Object)` and `Multimap.replaceValues(K, java.lang.Iterable<? extends V>)` methods return collections that aren't synchronized.

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

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

    - #### unmodifiableMultimap

          public static <K,V> Multimap<K,V> unmodifiableMultimap(Multimap<K,V> delegate)

      Returns an unmodifiable view of the specified multimap. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an `UnsupportedOperationException`.

      Note that the generated multimap's `Multimap.removeAll(java.lang.Object)` and `Multimap.replaceValues(K, java.lang.Iterable<? extends V>)` methods return collections that are modifiable.

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

      Parameters:
        `delegate` - the multimap for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified multimap

    - #### unmodifiableMultimap

          @Deprecated
          public static <K,V> Multimap<K,V> unmodifiableMultimap(ImmutableMultimap<K,V> delegate)

      Deprecated. no need to use this
      Simply returns its argument.
      Since:
        10.0

    - #### synchronizedSetMultimap

          public static <K,V> SetMultimap<K,V> synchronizedSetMultimap(SetMultimap<K,V> multimap)

      Returns a synchronized (thread-safe) `SetMultimap` backed by the specified multimap.

      You must follow the warnings described in `synchronizedMultimap(com.google.common.collect.Multimap<K, V>)`.

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

      Parameters:
        `multimap` - the multimap to be wrapped
      Returns:
        a synchronized view of the specified multimap

    - #### unmodifiableSetMultimap

          public static <K,V> SetMultimap<K,V> unmodifiableSetMultimap(SetMultimap<K,V> delegate)

      Returns an unmodifiable view of the specified `SetMultimap`. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an `UnsupportedOperationException`.

      Note that the generated multimap's `Multimap.removeAll(java.lang.Object)` and `Multimap.replaceValues(K, java.lang.Iterable<? extends V>)` methods return collections that are modifiable.

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

      Parameters:
        `delegate` - the multimap for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified multimap

    - #### unmodifiableSetMultimap

          @Deprecated
          public static <K,V> SetMultimap<K,V> unmodifiableSetMultimap(ImmutableSetMultimap<K,V> delegate)

      Deprecated. no need to use this
      Simply returns its argument.
      Since:
        10.0

    - #### synchronizedSortedSetMultimap

          public static <K,V> SortedSetMultimap<K,V> synchronizedSortedSetMultimap(SortedSetMultimap<K,V> multimap)

      Returns a synchronized (thread-safe) `SortedSetMultimap` backed by the specified multimap.

      You must follow the warnings described in `synchronizedMultimap(com.google.common.collect.Multimap<K, V>)`.

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

      Parameters:
        `multimap` - the multimap to be wrapped
      Returns:
        a synchronized view of the specified multimap

    - #### unmodifiableSortedSetMultimap

          public static <K,V> SortedSetMultimap<K,V> unmodifiableSortedSetMultimap(SortedSetMultimap<K,V> delegate)

      Returns an unmodifiable view of the specified `SortedSetMultimap`. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an `UnsupportedOperationException`.

      Note that the generated multimap's `Multimap.removeAll(java.lang.Object)` and `Multimap.replaceValues(K, java.lang.Iterable<? extends V>)` methods return collections that are modifiable.

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

      Parameters:
        `delegate` - the multimap for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified multimap

    - #### synchronizedListMultimap

          public static <K,V> ListMultimap<K,V> synchronizedListMultimap(ListMultimap<K,V> multimap)

      Returns a synchronized (thread-safe) `ListMultimap` backed by the specified multimap.

      You must follow the warnings described in `synchronizedMultimap(com.google.common.collect.Multimap<K, V>)`.

      Parameters:
        `multimap` - the multimap to be wrapped
      Returns:
        a synchronized view of the specified multimap

    - #### unmodifiableListMultimap

          public static <K,V> ListMultimap<K,V> unmodifiableListMultimap(ListMultimap<K,V> delegate)

      Returns an unmodifiable view of the specified `ListMultimap`. Query operations on the returned multimap "read through" to the specified multimap, and attempts to modify the returned multimap, either directly or through the multimap's views, result in an `UnsupportedOperationException`.

      Note that the generated multimap's `Multimap.removeAll(java.lang.Object)` and `Multimap.replaceValues(K, java.lang.Iterable<? extends V>)` methods return collections that are modifiable.

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

      Parameters:
        `delegate` - the multimap for which an unmodifiable view is to be returned
      Returns:
        an unmodifiable view of the specified multimap

    - #### unmodifiableListMultimap

          @Deprecated
          public static <K,V> ListMultimap<K,V> unmodifiableListMultimap(ImmutableListMultimap<K,V> delegate)

      Deprecated. no need to use this
      Simply returns its argument.
      Since:
        10.0

    - #### asMap

          @Beta
          public static <K,V> java.util.Map<K,java.util.List<V>> asMap(ListMultimap<K,V> multimap)

      Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, List<V>>`.
      Since:
        15.0

    - #### asMap

          @Beta
          public static <K,V> java.util.Map<K,java.util.Set<V>> asMap(SetMultimap<K,V> multimap)

      Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, Set<V>>`.
      Since:
        15.0

    - #### asMap

          @Beta
          public static <K,V> java.util.Map<K,java.util.SortedSet<V>> asMap(SortedSetMultimap<K,V> multimap)

      Returns `multimap.asMap()`, with its type corrected from `Map<K, Collection<V>>` to `Map<K, SortedSet<V>>`.
      Since:
        15.0

    - #### asMap

          @Beta
          public static <K,V> java.util.Map<K,java.util.Collection<V>> asMap(Multimap<K,V> multimap)

      Returns `multimap.asMap()`. This is provided for parity with the other more strongly-typed `asMap()` implementations.
      Since:
        15.0

    - #### forMap

          public static <K,V> SetMultimap<K,V> forMap(java.util.Map<K,V> map)

      Returns a multimap view of the specified map. The multimap is backed by the map, so changes to the map are reflected in the multimap, and vice versa. If the map is modified while an iteration over one of the multimap's collection views is in progress (except through the iterator's own `remove` operation, or through the `setValue` operation on a map entry returned by the iterator), the results of the iteration are undefined.

      The multimap supports mapping removal, which removes the corresponding mapping from the map. It does not support any operations which might add mappings, such as `put`, `putAll` or `replaceValues`.

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

      Parameters:
        `map` - the backing map for the returned multimap view

    - #### transformValues

          public static <K,V1,V2> Multimap<K,V2> transformValues(Multimap<K,V1> fromMultimap,
                                                 Function<? super V1,V2> function)

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

             Multimap<String, Integer> multimap =
               ImmutableSetMultimap.of("a", 2, "b", -3, "b", -3, "a", 4, "c", 6);
           Function<Integer, String> square = new Function<Integer, String>() {
               public String apply(Integer in) {
                 return Integer.toString(in * in);
               }
           };
           Multimap<String, String> transformed =
               Multimaps.transformValues(multimap, square);
             System.out.println(transformed);

      ... prints `{a=[4, 16], b=[9, 9], c=[36]}`.

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

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

      The returned multimap is not thread-safe or serializable, even if the underlying multimap is. The `equals` and `hashCode` methods of the returned multimap are meaningless, since there is not a definition of `equals` or `hashCode` for general collections, and `get()` will return a general `Collection` as opposed to a `List` or a `Set`.

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

      Since:
        7.0

    - #### transformEntries

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

      Returns a view of a multimap whose values are derived from the original multimap's entries. In contrast to `transformValues(com.google.common.collect.Multimap<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 multimap, such as iteration order, are left intact. For example, the code:

             SetMultimap<String, Integer> multimap =
                 ImmutableSetMultimap.of("a", 1, "a", 4, "b", -6);
             EntryTransformer<String, Integer, String> transformer =
                 new EntryTransformer<String, Integer, String>() {
                   public String transformEntry(String key, Integer value) {
                      return (value >= 0) ? key : "no" + key;
                   }
                 };
             Multimap<String, String> transformed =
                 Multimaps.transformEntries(multimap, transformer);
             System.out.println(transformed);

      ... prints `{a=[a, a], b=[nob]}`.

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

      It's acceptable for the underlying multimap to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed multimap might contain null values if the transformer sometimes gives a null result.

      The returned multimap is not thread-safe or serializable, even if the underlying multimap is. The `equals` and `hashCode` methods of the returned multimap are meaningless, since there is not a definition of `equals` or `hashCode` for general collections, and `get()` will return a general `Collection` as opposed to a `List` or a `Set`.

      The transformer is applied lazily, invoked when needed. This is necessary for the returned multimap to be a view, but it means that the transformer will be applied many times for bulk operations like `Multimap.containsValue(java.lang.Object)` and `Object.toString()`. For this to perform well, `transformer` should be fast. To avoid lazy evaluation when the returned multimap doesn't need to be a view, copy the returned multimap into a new multimap 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 multimap.

      Since:
        7.0

    - #### transformValues

          public static <K,V1,V2> ListMultimap<K,V2> transformValues(ListMultimap<K,V1> fromMultimap,
                                                     Function<? super V1,V2> function)

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

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

      ... prints `{a=[2.0, 4.0], b=[3.0]}`.

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

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

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

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

      Since:
        7.0

    - #### transformEntries

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

      Returns a view of a `ListMultimap` whose values are derived from the original multimap's entries. In contrast to `transformValues(ListMultimap, Function)`, this method's entry-transformation logic may depend on the key as well as the value.

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

             Multimap<String, Integer> multimap =
                 ImmutableMultimap.of("a", 1, "a", 4, "b", 6);
             EntryTransformer<String, Integer, String> transformer =
                 new EntryTransformer<String, Integer, String>() {
                   public String transformEntry(String key, Integer value) {
                     return key + value;
                   }
                 };
             Multimap<String, String> transformed =
                 Multimaps.transformEntries(multimap, transformer);
             System.out.println(transformed);

      ... prints `{"a"=["a1", "a4"], "b"=["b6"]}`.

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

      It's acceptable for the underlying multimap to contain null keys and null values provided that the transformer is capable of accepting null inputs. The transformed multimap might contain null values if the transformer sometimes gives a null result.

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

      The transformer is applied lazily, invoked when needed. This is necessary for the returned multimap to be a view, but it means that the transformer will be applied many times for bulk operations like `Multimap.containsValue(java.lang.Object)` and `Object.toString()`. For this to perform well, `transformer` should be fast. To avoid lazy evaluation when the returned multimap doesn't need to be a view, copy the returned multimap into a new multimap 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 multimap.

      Since:
        7.0

    - #### index

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

      Creates an index `ImmutableListMultimap` that contains the results of applying a specified function to each item in an `Iterable` of values. Each value will be stored as a value in the resulting multimap, yielding a multimap with the same size as the input iterable. The key used to store that value in the multimap will be the result of calling the function on that value. The resulting multimap is created as an immutable snapshot. In the returned multimap, keys appear in the order they are first encountered, and the values corresponding to each key appear in the same order as they are encountered.

      For example,

             List<String> badGuys =
                 Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
             Function<String, Integer> stringLengthFunction = ...;
             Multimap<Integer, String> index =
                 Multimaps.index(badGuys, stringLengthFunction);
             System.out.println(index);

      prints

             {4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}

      The returned multimap is serializable if its keys and values are all serializable.

      Parameters:
        `values` - the values to use when constructing the `ImmutableListMultimap`
        `keyFunction` - the function used to produce the key for each value
      Returns:
        `ImmutableListMultimap` mapping the result of evaluating the function `keyFunction` on each value in the input collection to that value
      Throws:
        `java.lang.NullPointerException` - if any of the following cases is true:
        - `values` is null
        - `keyFunction` is null
        - An element in `values` is null
        - `keyFunction` returns `null` for any element of `values`

    - #### index

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

      Creates an index `ImmutableListMultimap` that contains the results of applying a specified function to each item in an `Iterator` of values. Each value will be stored as a value in the resulting multimap, yielding a multimap with the same size as the input iterator. The key used to store that value in the multimap will be the result of calling the function on that value. The resulting multimap is created as an immutable snapshot. In the returned multimap, keys appear in the order they are first encountered, and the values corresponding to each key appear in the same order as they are encountered.

      For example,

             List<String> badGuys =
                 Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
             Function<String, Integer> stringLengthFunction = ...;
             Multimap<Integer, String> index =
                 Multimaps.index(badGuys.iterator(), stringLengthFunction);
             System.out.println(index);

      prints

             {4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}

      The returned multimap is serializable if its keys and values are all serializable.

      Parameters:
        `values` - the values to use when constructing the `ImmutableListMultimap`
        `keyFunction` - the function used to produce the key for each value
      Returns:
        `ImmutableListMultimap` mapping the result of evaluating the function `keyFunction` on each value in the input collection to that value
      Throws:
        `java.lang.NullPointerException` - if any of the following cases is true:
        - `values` is null
        - `keyFunction` is null
        - An element in `values` is null
        - `keyFunction` returns `null` for any element of `values`
      Since:
        10.0

    - #### filterKeys

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

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

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

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

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

      Many of the filtered multimap's methods, such as `size()`, iterate across every key/value mapping in the underlying multimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered multimap 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

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

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

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

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

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

      Many of the filtered multimap's methods, such as `size()`, iterate across every key/value mapping in the underlying multimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered multimap 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> ListMultimap<K,V> filterKeys(ListMultimap<K,V> unfiltered,
                                                            Predicate<? super K> keyPredicate)

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

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

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

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

      Many of the filtered multimap's methods, such as `size()`, iterate across every key/value mapping in the underlying multimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered multimap 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

    - #### filterValues

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

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

      The resulting multimap's views have iterators that don't support `remove()`, but all other methods are supported by the multimap and its views. When adding a value that doesn't satisfy the predicate, the multimap's `put()`, `putAll()`, and `replaceValues()` methods throw an `IllegalArgumentException`.

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

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

      Many of the filtered multimap's methods, such as `size()`, iterate across every key/value mapping in the underlying multimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered multimap 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

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

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

      The resulting multimap's views have iterators that don't support `remove()`, but all other methods are supported by the multimap and its views. When adding a value that doesn't satisfy the predicate, the multimap's `put()`, `putAll()`, and `replaceValues()` methods throw an `IllegalArgumentException`.

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

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

      Many of the filtered multimap's methods, such as `size()`, iterate across every key/value mapping in the underlying multimap and determine which satisfy the filter. When a live view is not needed, it may be faster to copy the filtered multimap 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

    - #### filterEntries

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

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

      The resulting multimap's views have iterators that don't support `remove()`, but all other methods are supported by the multimap and its views. When adding a key/value pair that doesn't satisfy the predicate, multimap's `put()`, `putAll()`, and `replaceValues()` methods throw an `IllegalArgumentException`.

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

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

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

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

      Since:
        11.0

    - #### filterEntries

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

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

      The resulting multimap's views have iterators that don't support `remove()`, but all other methods are supported by the multimap and its views. When adding a key/value pair that doesn't satisfy the predicate, multimap's `put()`, `putAll()`, and `replaceValues()` methods throw an `IllegalArgumentException`.

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

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

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

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

      Since:
        14.0