Multimap
Date: 2016-05-24

com.google.common.collect

## Interface Multimap<K,V>

- All Known Subinterfaces:
    ListMultimap<K,V>, SetMultimap<K,V>, SortedSetMultimap<K,V>
  All Known Implementing Classes:
    ArrayListMultimap, ForwardingListMultimap, ForwardingMultimap, ForwardingSetMultimap, ForwardingSortedSetMultimap, HashMultimap, ImmutableListMultimap, ImmutableMultimap, ImmutableSetMultimap, LinkedHashMultimap, LinkedListMultimap, TreeMultimap

      @GwtCompatible
      public interface Multimap<K,V>

  A collection that maps keys to values, similar to `Map`, but in which each key may be associated with multiple values. You can visualize the contents of a multimap either as a map from keys to nonempty collections of values:
  - a → 1, 2
  - b → 3
  ... or as a single "flattened" collection of key-value pairs:
  - a → 1
  - a → 2
  - b → 3

  Important: although the first interpretation resembles how most multimaps are implemented, the design of the `Multimap` API is based on the second form. So, using the multimap shown above as an example, the `size()` is `3`, not `2`, and the `values()` collection is `[1, 2, 3]`, not `[[1, 2], [3]]`. For those times when the first style is more useful, use the multimap's `asMap()` view (or create a `Map<K, Collection<V>>` in the first place).

  ### Example

  The following code:

         ListMultimap<String, String> multimap = ArrayListMultimap.create();
         for (President pres : US_PRESIDENTS_IN_ORDER) {
           multimap.put(pres.firstName(), pres.lastName());
         }
         for (String firstName : multimap.keySet()) {
           List<String> lastNames = multimap.get(firstName);
           out.println(firstName + ": " + lastNames);
         }

  ... produces output such as:

         Zachary: [Taylor]
         John: [Adams, Adams, Tyler, Kennedy]  // Remember, Quincy!
         George: [Washington, Bush, Bush]
         Grover: [Cleveland, Cleveland]        // Two, non-consecutive terms, rep'ing NJ!
         ...

  ### Views

  Much of the power of the multimap API comes from the view collections it provides. These always reflect the latest state of the multimap itself. When they support modification, the changes are write-through (they automatically update the backing multimap). These view collections are:

  - `asMap()`, mentioned above
  - `keys()`, `keySet()`, `values()`, `entries()`, which are similar to the corresponding view collections of `Map`
  - and, notably, even the collection returned by `get(key)` is an active view of the values corresponding to `key`

  The collections returned by the `replaceValues` and `removeAll` methods, which contain values that have just been removed from the multimap, are naturally not views.

  ### Subinterfaces

  Instead of using the `Multimap` interface directly, prefer the subinterfaces `ListMultimap` and `SetMultimap`. These take their names from the fact that the collections they return from `get` behave like (and, of course, implement) `List` and `Set`, respectively.

  For example, the "presidents" code snippet above used a `ListMultimap`; if it had used a `SetMultimap` instead, two presidents would have vanished, and last names might or might not appear in chronological order.

  Warning: instances of type `Multimap` may not implement `Object.equals(java.lang.Object)` in the way you expect. Multimaps containing the same key-value pairs, even in the same order, may or may not be equal and may or may not have the same `hashCode`. The recommended subinterfaces provide much stronger guarantees.

  ### Comparison to a map of collections

  Multimaps are commonly used in places where a `Map<K, Collection<V>>` would otherwise have appeared. The differences include:

  - There is no need to populate an empty collection before adding an entry with `put`.
  - `get` never returns `null`, only an empty collection.
  - A key is contained in the multimap if and only if it maps to at least one value. Any operation that causes a key to have zero associated values has the effect of removing that key from the multimap.
  - The total entry count is available as `size()`.
  - Many complex operations become easier; for example, `Collections.min(multimap.values())` finds the smallest value across all keys.

  ### Implementations

  As always, prefer the immutable implementations, `ImmutableListMultimap` and `ImmutableSetMultimap`. General-purpose mutable implementations are listed above under "All Known Implementing Classes". You can also create a custom multimap, backed by any `Map` and `Collection` types, using the `Multimaps.newMultimap` family of methods. Finally, another popular way to obtain a multimap is using `Multimaps.index`. See the `Multimaps` class for these and other static utilities related to multimaps.

  ### Other Notes

  As with `Map`, the behavior of a `Multimap` is not specified if key objects already present in the multimap change in a manner that affects `equals` comparisons. Use caution if mutable objects are used as keys in a `Multimap`.

  All methods that modify the multimap are optional. The view collections returned by the multimap may or may not be modifiable. Any modification method that is not supported will throw `UnsupportedOperationException`.

  See the Guava User Guide article on `Multimap`.

  Since:
    2.0

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map<K,java.util.Collection<V>>` | `asMap()` Returns a view of this multimap as a `Map` from each distinct key to the nonempty collection of that key's associated values.
    `void` | `clear()` Removes all key-value pairs from the multimap, leaving it empty.
    `boolean` | `containsEntry(java.lang.Object key, java.lang.Object value)` Returns `true` if this multimap contains at least one key-value pair with the key `key` and the value `value`.
    `boolean` | `containsKey(java.lang.Object key)` Returns `true` if this multimap contains at least one key-value pair with the key `key`.
    `boolean` | `containsValue(java.lang.Object value)` Returns `true` if this multimap contains at least one key-value pair with the value `value`.
    `java.util.Collection<java.util.Map.Entry<K,V>>` | `entries()` Returns a view collection of all key-value pairs contained in this multimap, as `Map.Entry` instances.
    `boolean` | `equals(java.lang.Object obj)` Compares the specified object with this multimap for equality.
    `java.util.Collection<V>` | `get(K key)` Returns a view collection of the values associated with `key` in this multimap, if any.
    `int` | `hashCode()` Returns the hash code for this multimap.
    `boolean` | `isEmpty()` Returns `true` if this multimap contains no key-value pairs.
    `Multiset<K>` | `keys()` Returns a view collection containing the key from each key-value pair in this multimap, without collapsing duplicates.
    `java.util.Set<K>` | `keySet()` Returns a view collection of all distinct keys contained in this multimap.
    `boolean` | `put(K key, V value)` Stores a key-value pair in this multimap.
    `boolean` | `putAll(K key, java.lang.Iterable<? extends V> values)` Stores a key-value pair in this multimap for each of `values`, all using the same key, `key`.
    `boolean` | `putAll(Multimap<? extends K,? extends V> multimap)` Stores all key-value pairs of `multimap` in this multimap, in the order returned by `multimap.entries()`.
    `boolean` | `remove(java.lang.Object key, java.lang.Object value)` Removes a single key-value pair with the key `key` and the value `value` from this multimap, if such exists.
    `java.util.Collection<V>` | `removeAll(java.lang.Object key)` Removes all values associated with the key `key`.
    `java.util.Collection<V>` | `replaceValues(K key, java.lang.Iterable<? extends V> values)` Stores a collection of values with the same key, replacing any existing values for that key.
    `int` | `size()` Returns the number of key-value pairs in this multimap.
    `java.util.Collection<V>` | `values()` Returns a view collection containing the value from each key-value pair contained in this multimap, without collapsing duplicates (so `values().size() == size()`).

- - ### Method Detail

    - #### size

          int size()

      Returns the number of key-value pairs in this multimap.

      Note: this method does not return the number of distinct keys in the multimap, which is given by `keySet().size()` or `asMap().size()`. See the opening section of the `Multimap` class documentation for clarification.

    - #### isEmpty

          boolean isEmpty()

      Returns `true` if this multimap contains no key-value pairs. Equivalent to `size() == 0`, but can in some cases be more efficient.

    - #### containsKey

          boolean containsKey(@Nullable
                            java.lang.Object key)

      Returns `true` if this multimap contains at least one key-value pair with the key `key`.

    - #### containsValue

          boolean containsValue(@Nullable
                              java.lang.Object value)

      Returns `true` if this multimap contains at least one key-value pair with the value `value`.

    - #### containsEntry

          boolean containsEntry(@Nullable
                              java.lang.Object key,
                              @Nullable
                              java.lang.Object value)

      Returns `true` if this multimap contains at least one key-value pair with the key `key` and the value `value`.

    - #### put

          boolean put(@Nullable
                    K key,
                    @Nullable
                    V value)

      Stores a key-value pair in this multimap.

      Some multimap implementations allow duplicate key-value pairs, in which case `put` always adds a new key-value pair and increases the multimap size by 1. Other implementations prohibit duplicates, and storing a key-value pair that's already in the multimap has no effect.

      Returns:
        `true` if the method increased the size of the multimap, or `false` if the multimap already contained the key-value pair and doesn't allow duplicates

    - #### remove

          boolean remove(@Nullable
                       java.lang.Object key,
                       @Nullable
                       java.lang.Object value)

      Removes a single key-value pair with the key `key` and the value `value` from this multimap, if such exists. If multiple key-value pairs in the multimap fit this description, which one is removed is unspecified.
      Returns:
        `true` if the multimap changed

    - #### putAll

          boolean putAll(@Nullable
                       K key,
                       java.lang.Iterable<? extends V> values)

      Stores a key-value pair in this multimap for each of `values`, all using the same key, `key`. Equivalent to (but expected to be more efficient than):

             for (V value : values) {
               put(key, value);
             }

      In particular, this is a no-op if `values` is empty.

      Returns:
        `true` if the multimap changed

    - #### putAll

          boolean putAll(Multimap<? extends K,? extends V> multimap)

      Stores all key-value pairs of `multimap` in this multimap, in the order returned by `multimap.entries()`.
      Returns:
        `true` if the multimap changed

    - #### replaceValues

          java.util.Collection<V> replaceValues(@Nullable
                                              K key,
                                              java.lang.Iterable<? extends V> values)

      Stores a collection of values with the same key, replacing any existing values for that key.

      If `values` is empty, this is equivalent to `removeAll(key)`.

      Returns:
        the collection of replaced values, or an empty collection if no values were previously associated with the key. The collection may be modifiable, but updating it will have no effect on the multimap.

    - #### removeAll

          java.util.Collection<V> removeAll(@Nullable
                                          java.lang.Object key)

      Removes all values associated with the key `key`.

      Once this method returns, `key` will not be mapped to any values, so it will not appear in `keySet()`, `asMap()`, or any other views.

      Returns:
        the values that were removed (possibly empty). The returned collection may be modifiable, but updating it will have no effect on the multimap.

    - #### clear

          void clear()

      Removes all key-value pairs from the multimap, leaving it empty.

    - #### get

          java.util.Collection<V> get(@Nullable
                                    K key)

      Returns a view collection of the values associated with `key` in this multimap, if any. Note that when `containsKey(key)` is false, this returns an empty collection, not `null`.

      Changes to the returned collection will update the underlying multimap, and vice versa.

    - #### keySet

          java.util.Set<K> keySet()

      Returns a view collection of all distinct keys contained in this multimap. Note that the key set contains a key if and only if this multimap maps that key to at least one value.

      Changes to the returned set will update the underlying multimap, and vice versa. However, adding to the returned set is not possible.

    - #### keys

          Multiset<K> keys()

      Returns a view collection containing the key from each key-value pair in this multimap, without collapsing duplicates. This collection has the same size as this multimap, and `keys().count(k) == get(k).size()` for all `k`.

      Changes to the returned multiset will update the underlying multimap, and vice versa. However, adding to the returned collection is not possible.

    - #### values

          java.util.Collection<V> values()

      Returns a view collection containing the value from each key-value pair contained in this multimap, without collapsing duplicates (so `values().size() == size()`).

      Changes to the returned collection will update the underlying multimap, and vice versa. However, adding to the returned collection is not possible.

    - #### entries

          java.util.Collection<java.util.Map.Entry<K,V>> entries()

      Returns a view collection of all key-value pairs contained in this multimap, as `Map.Entry` instances.

      Changes to the returned collection or the entries it contains will update the underlying multimap, and vice versa. However, adding to the returned collection is not possible.

    - #### asMap

          java.util.Map<K,java.util.Collection<V>> asMap()

      Returns a view of this multimap as a `Map` from each distinct key to the nonempty collection of that key's associated values. Note that `this.asMap().get(k)` is equivalent to `this.get(k)` only when `k` is a key contained in the multimap; otherwise it returns `null` as opposed to an empty collection.

      Changes to the returned map or the collections that serve as its values will update the underlying multimap, and vice versa. The map does not support `put` or `putAll`, nor do its entries support `setValue`.

    - #### equals

          boolean equals(@Nullable
                       java.lang.Object obj)

      Compares the specified object with this multimap for equality. Two multimaps are equal when their map views, as returned by `asMap()`, are also equal.

      In general, two multimaps with identical key-value mappings may or may not be equal, depending on the implementation. For example, two `SetMultimap` instances with the same key-value mappings are equal, but equality of two `ListMultimap` instances depends on the ordering of the values for each key.

      A non-empty `SetMultimap` cannot be equal to a non-empty `ListMultimap`, since their `asMap()` views contain unequal collections as values. However, any two empty multimaps are equal, because they both have empty `asMap()` views.

      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          int hashCode()

      Returns the hash code for this multimap.

      The hash code of a multimap is defined as the hash code of the map view, as returned by `asMap()`.

      In general, two multimaps with identical key-value mappings may or may not have the same hash codes, depending on the implementation. For example, two `SetMultimap` instances with the same key-value mappings will have the same `hashCode`, but the `hashCode` of `ListMultimap` instances depends on the ordering of the values for each key.

      Overrides:
        `hashCode` in class `java.lang.Object`