diff options
Diffstat (limited to 'guava/src/com/google/common/collect/Multimap.java')
-rw-r--r-- | guava/src/com/google/common/collect/Multimap.java | 157 |
1 files changed, 28 insertions, 129 deletions
diff --git a/guava/src/com/google/common/collect/Multimap.java b/guava/src/com/google/common/collect/Multimap.java index ed5afb3..900f820 100644 --- a/guava/src/com/google/common/collect/Multimap.java +++ b/guava/src/com/google/common/collect/Multimap.java @@ -19,139 +19,40 @@ package com.google.common.collect; import com.google.common.annotations.GwtCompatible; import java.util.Collection; -import java.util.List; import java.util.Map; import java.util.Set; import javax.annotation.Nullable; /** - * A collection that maps keys to values, similar to {@link Map}, but in which - * each key may be associated with <i>multiple</i> values. You can visualize the - * contents of a multimap either as a map from keys to <i>nonempty</i> - * collections of values: + * A collection similar to a {@code Map}, but which may associate multiple + * values with a single key. If you call {@link #put} twice, with the same key + * but different values, the multimap contains mappings from the key to both + * values. * - * <ul> - * <li>a → 1, 2 - * <li>b → 3 - * </ul> + * <p>The methods {@link #get}, {@link #keySet}, {@link #keys}, {@link #values}, + * {@link #entries}, and {@link #asMap} return collections that are views of the + * multimap. If the multimap is modifiable, updating it can change the contents + * of those collections, and updating the collections will change the multimap. + * In contrast, {@link #replaceValues} and {@link #removeAll} return collections + * that are independent of subsequent multimap changes. * - * ... or as a single "flattened" collection of key-value pairs: + * <p>Depending on the implementation, a multimap may or may not allow duplicate + * key-value pairs. In other words, the multimap contents after adding the same + * key and value twice varies between implementations. In multimaps allowing + * duplicates, the multimap will contain two mappings, and {@code get} will + * return a collection that includes the value twice. In multimaps not + * supporting duplicates, the multimap will contain a single mapping from the + * key to the value, and {@code get} will return a collection that includes the + * value once. * - * <ul> - * <li>a → 1 - * <li>a → 2 - * <li>b → 3 - * </ul> - * - * <p><b>Important:</b> although the first interpretation resembles how most - * multimaps are <i>implemented</i>, the design of the {@code Multimap} API is - * based on the <i>second</i> form. So, using the multimap shown above as an - * example, the {@link #size} is {@code 3}, not {@code 2}, and the {@link - * #values} collection is {@code [1, 2, 3]}, not {@code [[1, 2], [3]]}. For - * those times when the first style is more useful, use the multimap's {@link - * #asMap} view (or create a {@code Map<K, Collection<V>>} in the first place). - * - * <h3>Example</h3> - * - * <p>The following code: <pre> {@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); - * }}</pre> - * - * ... produces output such as: <pre> {@code - * - * Zachary: [Taylor] - * John: [Adams, Adams, Tyler, Kennedy] - * George: [Washington, Bush, Bush] - * Grover: [Cleveland] - * ...}</pre> - * - * <h3>Views</h3> - * - * <p>Much of the power of the multimap API comes from the <i>view - * collections</i> it provides. These always reflect the latest state of the - * multimap itself. When they support modification, the changes are - * <i>write-through</i> (they automatically update the backing multimap). These - * view collections are: - * - * <ul> - * <li>{@link #asMap}, mentioned above</li> - * <li>{@link #keys}, {@link #keySet}, {@link #values}, {@link #entries}, which - * are similar to the corresponding view collections of {@link Map} - * <li>and, notably, even the collection returned by {@link #get get(key)} is an - * active view of the values corresponding to {@code key} - * </ul> - * - * <p>The collections returned by the {@link #replaceValues replaceValues} and - * {@link #removeAll removeAll} methods, which contain values that have just - * been removed from the multimap, are naturally <i>not</i> views. - * - * <h3>Subinterfaces</h3> - * - * <p>Instead of using the {@code Multimap} interface directly, prefer the - * subinterfaces {@link ListMultimap} and {@link SetMultimap}. These take their - * names from the fact that the collections they return from {@code get} behave - * like (and, of course, implement) {@link List} and {@link Set}, respectively. - * - * <p>For example, the "presidents" code snippet above used a {@code - * ListMultimap}; if it had used a {@code SetMultimap} instead, two presidents - * would have vanished, and last names might or might not appear in - * chronological order. - * - * <p><b>Warning:</b> instances of type {@code Multimap} may not implement - * {@link Object#equals} in the way you expect (multimaps containing the same - * key-value pairs, even in the same order, may or may not be equal). The - * recommended subinterfaces provide a much stronger guarantee. - * - * <h3>Comparison to a map of collections</h3> - * - * <p>Multimaps are commonly used in places where a {@code Map<K, - * Collection<V>>} would otherwise have appeared. The differences include: - * - * <ul> - * <li>There is no need to populate an empty collection before adding an entry - * with {@link #put put}. - * <li>{@code get} never returns {@code null}, only an empty collection. - * <li>A key contained in the multimap always maps to at least one value. Any - * operation that causes a key to have zero associated values has the effect - * of <i>removing</i> that key from the multimap. - * <li>The total entry count is available as {@link #size}. - * <li>Many complex operations become easier; for example, {@code - * Collections.min(multimap.values())} finds the smallest value across all - * keys. - * </ul> - * - * <h3>Implementations</h3> - * - * <p>As always, prefer the immutable implementations, {@link - * ImmutableListMultimap} and {@link ImmutableSetMultimap}. General-purpose - * mutable implementations are listed above under "All Known Implementing - * Classes". You can also create a <i>custom</i> multimap, backed by any {@code - * Map} and {@link Collection} types, using the {@link Multimaps#newMultimap - * Multimaps.newMultimap} family of methods. Finally, another popular way to - * obtain a multimap is using {@link Multimaps#index Multimaps.index}. See - * the {@link Multimaps} class for these and other static utilities related - * to multimaps. - * - * <h3>Other Notes</h3> - * - * <p>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 {@link - * UnsupportedOperationException}. - * - * <p>See the Guava User Guide article on <a href= - * "http://code.google.com/p/guava-libraries/wiki/NewCollectionTypesExplained#Multimap"> - * {@code Multimap}</a>. + * <p>All methods that alter the multimap are optional, and the views returned + * by the multimap may or may not be modifiable. When modification isn't + * supported, those methods will throw an {@link UnsupportedOperationException}. * * @author Jared Levy + * @param <K> the type of keys maintained by this multimap + * @param <V> the type of mapped values * @since 2.0 (imported from Google Collections Library) */ @GwtCompatible @@ -207,7 +108,7 @@ public interface Multimap<K, V> { boolean put(@Nullable K key, @Nullable V value); /** - * Removes a single key-value pair from the multimap. + * Removes a key-value pair from the multimap. * * @param key key of entry to remove from the multimap * @param value value of entry to remove the multimap @@ -268,17 +169,15 @@ public interface Multimap<K, V> { // Views /** - * Returns a collection view containing the values associated with {@code key} - * in this multimap, if any. Note that even when ({@code containsKey(key)} is - * false, {@code get(key)} still returns an empty collection, not {@code - * null}. + * Returns a collection view of all values associated with a key. If no + * mappings in the multimap have the provided key, an empty collection is + * returned. * * <p>Changes to the returned collection will update the underlying multimap, * and vice versa. * * @param key key to search for in multimap - * @return a view collection containing the zero or more values that the key - * maps to + * @return the collection of values that the key maps to */ Collection<V> get(@Nullable K key); |