Interface Multimap<K,V>
- Type Parameters:
K
- the type of keys usedV
- the type of mapped values
- All Known Subinterfaces:
BagMultimap<K,
,V> ImmutableBagIterableMultimap<K,
,V> ImmutableBagMultimap<K,
,V> ImmutableListMultimap<K,
,V> ImmutableMultimap<K,
,V> ImmutableSetIterableMultimap<K,
,V> ImmutableSetMultimap<K,
,V> ImmutableSortedBagMultimap<K,
,V> ImmutableSortedSetMultimap<K,
,V> ListMultimap<K,
,V> MutableBagIterableMultimap<K,
,V> MutableBagMultimap<K,
,V> MutableListMultimap<K,
,V> MutableMultimap<K,
,V> MutableSetIterableMultimap<K,
,V> MutableSetMultimap<K,
,V> MutableSortedBagMultimap<K,
,V> MutableSortedSetMultimap<K,
,V> OrderedIterableMultimap<K,
,V> ReversibleIterableMultimap<K,
,V> SetMultimap<K,
,V> SortedBagMultimap<K,
,V> SortedIterableMultimap<K,
,V> SortedSetMultimap<K,
,V> UnsortedBagMultimap<K,
,V> UnsortedSetMultimap<K,
V>
- All Known Implementing Classes:
AbstractImmutableMultimap
,AbstractMultimap
,AbstractMutableBagMultimap
,AbstractMutableListMultimap
,AbstractMutableMultimap
,AbstractMutableSetMultimap
,AbstractSynchronizedMultimap
,AbstractSynchronizedPutMultimap
,FastListMultimap
,HashBagMultimap
,HashBagMultimapWithHashingStrategy
,ImmutableBagMultimapImpl
,ImmutableListMultimapImpl
,ImmutableSetMultimapImpl
,ImmutableSortedBagMultimapImpl
,ImmutableSortedSetMultimapImpl
,MultiReaderFastListMultimap
,MultiReaderHashBagMultimap
,MultiReaderUnifiedSetMultimap
,SynchronizedBagMultimap
,SynchronizedListMultimap
,SynchronizedPutFastListMultimap
,SynchronizedPutHashBagMultimap
,SynchronizedPutTreeSortedSetMultimap
,SynchronizedPutUnifiedSetMultimap
,SynchronizedSetMultimap
,SynchronizedSortedBagMultimap
,SynchronizedSortedSetMultimap
,TreeBagMultimap
,TreeBagMultimap
,TreeBagMultimap
,TreeSortedSetMultimap
,UnifiedSetMultimap
,UnifiedSetWithHashingStrategyMultimap
Map
that can associate multiple values for keys.
Unlike Map
however, this interface is read-only so the results of access methods such as get(Object)
return a view onto the values associated with that key. The MutableMultimap
sub-interface
provides methods to mutate the collection.
The advantages to using this container over a Map<K, Collection<V>>
is that all of the handling of the
value collection can be done automatically. It also allows implementations to further specialize in how duplicate
values will be handled. Value collections with list semantics would allow duplicate values for a key, while those
implementing set semantics would not. The value collections can never be empty.
Internal iteration methods for keys and values (singly - forEachKey(Procedure)
, forEachValue(Procedure)
,
and together - forEachKeyValue(Procedure2)
), forEachKeyMultiValues(Procedure2)
) are provided to allow flexible
browsing of the collection's contents. Similarly, views also are provided for keys (keysView()
), values
(valuesView()
) and the combination thereof (keyValuePairsView()
, keyMultiValuePairsView()
).
- Since:
- 1.0
-
Method Summary
Modifier and TypeMethodDescription<K2,
V2> Multimap<K2, V2> collectKeyMultiValues
(Function<? super K, ? extends K2> keyFunction, Function<? super V, ? extends V2> valueFunction) Returns a new multimap with the results of applying the specified keyFunction and valueFunction on each key and corresponding values of the source multimap.<K2,
V2, R extends MutableMultimap<K2, V2>>
RcollectKeyMultiValues
(Function<? super K, ? extends K2> keyFunction, Function<? super V, ? extends V2> valueFunction, R target) Same as the collectKeyMultiValues method but uses the specified target multimap for the results.<K2,
V2> Multimap<K2, V2> collectKeysValues
(Function2<? super K, ? super V, Pair<K2, V2>> function) Returns a new multimap with the results of applying the specified function on each key and value of the source multimap.<K2,
V2, R extends MutableMultimap<K2, V2>>
RcollectKeysValues
(Function2<? super K, ? super V, Pair<K2, V2>> function, R target) Same as the collect method but uses the specified target multimap for the results.collectValues
(Function<? super V, ? extends V2> function) Returns a new multimap with the results of applying the specified function on each value of the source multimap.<V2,
R extends MutableMultimap<K, V2>>
RcollectValues
(Function<? super V, ? extends V2> function, R target) Same as the collect method but uses the specified target multimap for the results.boolean
containsKey
(Object key) Returnstrue
if any values are mapped to the specified key.boolean
containsKeyAndValue
(Object key, Object value) Returnstrue
if the specified key-value pair is mapped.boolean
containsValue
(Object value) Returnstrue
if any key is mapped to the specified value.boolean
Compares the specified object with this Multimap for equality.flip()
Given a Multimap from Domain->
Range return a multimap from Range->
Domain.void
forEachKey
(Procedure<? super K> procedure) Calls theprocedure
with each key.void
forEachKeyMultiValues
(Procedure2<? super K, ? super RichIterable<V>> procedure) Calls theprocedure
with each key-Iterable[value].void
forEachKeyValue
(Procedure2<? super K, ? super V> procedure) Calls theprocedure
with each key-value pair.void
forEachValue
(Procedure<? super V> procedure) Calls the procedure with each value.Returns a view of all values associated with the given key.int
hashCode()
Returns the hash code for this Multimap.boolean
isEmpty()
Returnstrue
if there are no entries.keyBag()
Returns aBag
of keys with the count corresponding to the number of mapped values.Returns a lazy view of the pair of a key and a lazy view of the values mapped to that key.keySet()
Returns an unmodifiableSetIterable
of keys with O(1) complexity.keysView()
Returns a lazy view of the unique keys.RichIterable<Pair<K,
V>> Returns a lazy view of all the key/value pairs.Returns an unmodifiable view of all the values mapped to each key.newEmpty()
Creates a new instance of the same implementation type, using the default capacity and growth parameters.boolean
notEmpty()
Returnstrue
if there is at least one entry.rejectKeysMultiValues
(Predicate2<? super K, ? super RichIterable<V>> predicate) Returns all elements of the source multimap that don't satisfy the predicate.<R extends MutableMultimap<K,
V>>
RrejectKeysMultiValues
(Predicate2<? super K, ? super RichIterable<V>> predicate, R target) Same as the reject method but uses the specified target multimap for the results.rejectKeysValues
(Predicate2<? super K, ? super V> predicate) Returns all elements of the source multimap that don't satisfy the predicate.<R extends MutableMultimap<K,
V>>
RrejectKeysValues
(Predicate2<? super K, ? super V> predicate, R target) Same as the reject method but uses the specified target multimap for the results.selectKeysMultiValues
(Predicate2<? super K, ? super RichIterable<V>> predicate) Returns all elements of the source multimap that satisfies the predicate.<R extends MutableMultimap<K,
V>>
RselectKeysMultiValues
(Predicate2<? super K, ? super RichIterable<V>> predicate, R target) Same as the select method but uses the specified target multimap for the results.selectKeysValues
(Predicate2<? super K, ? super V> predicate) Returns all elements of the source multimap that satisfies the predicate.<R extends MutableMultimap<K,
V>>
RselectKeysValues
(Predicate2<? super K, ? super V> predicate, R target) Same as the select method but uses the specified target multimap for the results.int
size()
Returns the number of key-value entry pairs.int
Returns the number of distinct keys.Returns an immutable copy of this Multimap if it is not already immutable.toMap()
Returns a newMutableMap
of keys from this Multimap to the mapped values as aRichIterable
.<R extends Collection<V>>
MutableMap<K,R> Returns a newMutableMap
of keys from this Multimap to the mapped values as aRichIterable
.Returns a mutable copy of this Multimap.Returns a lazy flattened view of all the values.
-
Method Details
-
newEmpty
Creates a new instance of the same implementation type, using the default capacity and growth parameters. -
isEmpty
boolean isEmpty()Returnstrue
if there are no entries. -
notEmpty
boolean notEmpty()Returnstrue
if there is at least one entry. -
forEachValue
Calls the procedure with each value.Given a Multimap with the contents:
{"key1" : ["val1", "val2", "val2"], "key2" : ["val3"]}
["val1", "val2", "val2", "val3"]
-
forEachKey
Calls theprocedure
with each key.Given a Multimap with the contents:
{"key1" : ["val1", "val2", "val2"], "key2" : ["val3"]}
The given procedure would be invoked with the parameters:
["key1", "key2"]
-
forEachKeyValue
Calls theprocedure
with each key-value pair.Given a Multimap with the contents:
{"key1" : ["val1", "val2", "val2"], "key2" : ["val3"]}
The given procedure would be invoked with the parameters:
[["key1", "val1"], ["key1", "val2"], ["key1", "val2"], ["key2", "val3"]]
-
forEachKeyMultiValues
Calls theprocedure
with each key-Iterable[value].Given a Multimap with the contents:
{"key1" : ["val1", "val2", "val2"], "key2" : ["val3"]}
The given procedure would be invoked with the parameters:
[["key1", {@link RichIterable["val1", "val2", "val2"]}], ["key2", {@link RichIterable["val3"]}]]
- Since:
- 6.0
-
size
int size()Returns the number of key-value entry pairs.This method is implemented with O(1) (constant-time) performance.
-
sizeDistinct
int sizeDistinct()Returns the number of distinct keys. -
containsKey
Returnstrue
if any values are mapped to the specified key.- Parameters:
key
- the key to search for
-
containsValue
Returnstrue
if any key is mapped to the specified value.- Parameters:
value
- the value to search for
-
containsKeyAndValue
Returnstrue
if the specified key-value pair is mapped.- Parameters:
key
- the key to search forvalue
- the value to search for
-
get
Returns a view of all values associated with the given key.If the given key does not exist, an empty
RichIterable
is returned.- Parameters:
key
- the key to search for
-
keysView
RichIterable<K> keysView()Returns a lazy view of the unique keys. -
keySet
SetIterable<K> keySet()Returns an unmodifiableSetIterable
of keys with O(1) complexity. -
keyBag
Returns aBag
of keys with the count corresponding to the number of mapped values. -
multiValuesView
RichIterable<RichIterable<V>> multiValuesView()Returns an unmodifiable view of all the values mapped to each key. -
valuesView
RichIterable<V> valuesView()Returns a lazy flattened view of all the values. -
keyMultiValuePairsView
RichIterable<Pair<K,RichIterable<V>>> keyMultiValuePairsView()Returns a lazy view of the pair of a key and a lazy view of the values mapped to that key. -
keyValuePairsView
RichIterable<Pair<K,V>> keyValuePairsView()Returns a lazy view of all the key/value pairs. -
toMap
MutableMap<K,RichIterable<V>> toMap()Returns a newMutableMap
of keys from this Multimap to the mapped values as aRichIterable
. -
toMap
Returns a newMutableMap
of keys from this Multimap to the mapped values as aRichIterable
.- Parameters:
collectionFactory
- used to create the collections that hold the values and affects the return type
-
equals
Compares the specified object with this Multimap for equality.Two Multimaps are equal when their map views (as returned by
toMap()
) are also equal.In general, two Multimaps with identical key-value mappings may or may not be equal, depending on the type of the collections holding the values. If the backing collections are Sets, then two instances with the same key-value mappings are equal, but if the backing collections are Lists, equality depends on the ordering of the values for each key.
Any two empty Multimaps are equal, because they both have empty
toMap()
views. -
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
toMap()
. -
toMutable
MutableMultimap<K,V> toMutable()Returns a mutable copy of this Multimap. -
toImmutable
ImmutableMultimap<K,V> toImmutable()Returns an immutable copy of this Multimap if it is not already immutable. If the Multimap is immutable, it will return itself.The returned Multimap will be
Serializable
if this Multimap isSerializable
. -
flip
Given a Multimap from Domain->
Range return a multimap from Range->
Domain.- Since:
- 6.0
-
selectKeysValues
Returns all elements of the source multimap that satisfies the predicate. This method is also commonly called filter.e.g. return multimap.selectKeysValues(new Predicate2<Integer, Person>() { public boolean accept(Integer age, Person person) { return (age >= 18) && (person.getAddress().getCity().equals("Metuchen")); } });
- Parameters:
predicate
- aPredicate2
to use as the select criteria- Returns:
Multimap
, which contains elements as a result of the select criteria- Since:
- 6.0
-
selectKeysValues
<R extends MutableMultimap<K,V>> R selectKeysValues(Predicate2<? super K, ? super V> predicate, R target) Same as the select method but uses the specified target multimap for the results.e.g. return multimap.selectKeysValues(new Predicate2<Integer, Person>() { public boolean accept(Integer age, Person person) { return (age >= 18) && (person.getAddress().getCity().equals("Metuchen")); } }, FastListMultimap.newMultimap());
- Parameters:
predicate
- aPredicate2
to use as the select criteriatarget
- the Multimap to append to for all elements in thisMultimap
that satisfy thepredicate
- Returns:
target
, which contains appended elements as a result of the select criteria- Since:
- 6.0
-
rejectKeysValues
Returns all elements of the source multimap that don't satisfy the predicate.e.g. return multimap.rejectKeysValues(new Predicate2<Integer, Person>() { public boolean accept(Integer age, Person person) { return (age >= 18) && (person.getAddress().getCity().equals("Metuchen")); } });
- Parameters:
predicate
- aPredicate2
to use as the reject criteria- Returns:
Multimap
, which contains elements that don't satisfy thepredicate
- Since:
- 6.0
-
rejectKeysValues
<R extends MutableMultimap<K,V>> R rejectKeysValues(Predicate2<? super K, ? super V> predicate, R target) Same as the reject method but uses the specified target multimap for the results.e.g. return multimap.rejectKeysValues(new Predicate2<Integer, Person>() { public boolean accept(Integer age, Person person) { return (age >= 18) && (person.getAddress().getCity().equals("Metuchen")); } }, FastListMultimap.newMultimap());
- Parameters:
predicate
- aPredicate2
to use as the reject criteriatarget
- the Multimap to append to for all elements in thisMultimap
that don't satisfy thepredicate
- Returns:
target
, which contains appended elements that don't satisfy thepredicate
- Since:
- 6.0
-
selectKeysMultiValues
Returns all elements of the source multimap that satisfies the predicate. This method is also commonly called filter.e.g. return multimap.selectKeysMultiValues(new Predicate2<Integer, Iterable<Person>>() { public boolean accept(Integer age, Iterable<Person> values) { return (age >= 18) && ((RichIterable<Person>)values.size() >= 2); } });
- Parameters:
predicate
- aPredicate2
to use as the select criteria- Returns:
Multimap
, which contains elements as a result of the select criteria- Since:
- 6.0
-
selectKeysMultiValues
<R extends MutableMultimap<K,V>> R selectKeysMultiValues(Predicate2<? super K, ? super RichIterable<V>> predicate, R target) Same as the select method but uses the specified target multimap for the results.e.g. return multimap.selectKeysMultiValues(new Predicate2<Integer, Iterable<Person>>() { public boolean accept(Integer age, Iterable<Person> values) { return (age >= 18) && ((RichIterable<Person>)values.size() >= 2); } }, FastListMultimap.newMultimap());
- Parameters:
predicate
- aPredicate2
to use as the select criteriatarget
- the Multimap to append to for all elements in thisMultimap
that satisfy thepredicate
- Returns:
target
, which contains appended elements as a result of the select criteria- Since:
- 6.0
-
rejectKeysMultiValues
Returns all elements of the source multimap that don't satisfy the predicate.e.g. return multimap.rejectKeysMultiValues(new Predicate2<Integer, Iterable<Person>>() { public boolean accept(Integer age, Iterable<Person> values) { return (age >= 18) && ((RichIterable<Person>)values.size() >= 2); } });
- Parameters:
predicate
- aPredicate2
to use as the reject criteria- Returns:
Multimap
, which contains elements that don't satisfy thepredicate
- Since:
- 6.0
-
rejectKeysMultiValues
<R extends MutableMultimap<K,V>> R rejectKeysMultiValues(Predicate2<? super K, ? super RichIterable<V>> predicate, R target) Same as the reject method but uses the specified target multimap for the results.e.g. return multimap.rejectKeysMultiValues(new Predicate2<Integer, Iterable<Person>>() { public boolean accept(Integer age, Iterable<Person> values) { return (age >= 18) && ((RichIterable<Person>)values.size() >= 2); } }, FastListMultimap.newMultimap());
- Parameters:
predicate
- aPredicate2
to use as the reject criteriatarget
- the Multimap to append to for all elements in thisMultimap
that don't satisfy thepredicate
- Returns:
target
, which contains appended elements that don't satisfy thepredicate
- Since:
- 6.0
-
collectKeysValues
Returns a new multimap with the results of applying the specified function on each key and value of the source multimap. This method is also commonly called transform or map.e.g. return multimap.collectKeysValues(new Function2<Integer, Person, Pair<String, String>>() { public Pair<String, String> valueOf(Integer age, Person person) { return Tuples.pair(age.toString(), person.getLastName()); } });
- Parameters:
function
- aFunction2
to use for transformation- Returns:
Multimap
, which contains elements as a result of the transformation- Since:
- 6.0
-
collectKeysValues
<K2,V2, R collectKeysValuesR extends MutableMultimap<K2, V2>> (Function2<? super K, ? super V, Pair<K2, V2>> function, R target) Same as the collect method but uses the specified target multimap for the results.e.g. return multimap.collectKeysValues(new Function2<Integer, Person, Pair<String, String>>() { public Pair<String, String> valueOf(Integer age, Person person) { return Tuples.pair(age.toString(), person.getLastName()); } }, HashBagMultimap.<String, String>newMultimap());
- Parameters:
function
- aFunction2
to use for transformationtarget
- the Multimap to append for all elements in thisMultimap
that are evaluated infunction
- Returns:
target
, which contains appended elements as a result of the transformation- Since:
- 6.0
-
collectKeyMultiValues
<K2,V2> Multimap<K2,V2> collectKeyMultiValues(Function<? super K, ? extends K2> keyFunction, Function<? super V, ? extends V2> valueFunction) Returns a new multimap with the results of applying the specified keyFunction and valueFunction on each key and corresponding values of the source multimap. This method is also commonly called transform or map.e.g. return multimap.collectKeyMultiValues(each -> each + 1, Person::getLastName);
-
collectKeyMultiValues
<K2,V2, R collectKeyMultiValuesR extends MutableMultimap<K2, V2>> (Function<? super K, ? extends K2> keyFunction, Function<? super V, ? extends V2> valueFunction, R target) Same as the collectKeyMultiValues method but uses the specified target multimap for the results.e.g. return multimap.collectKeyMultiValues(each -> each + 1, Person::getLastName, HashBagMultimap.<Integer, String>newMultimap());
- Parameters:
keyFunction
-Function
to use transformation to get the keyvalueFunction
-Function
to use transformation to get the valuestarget
- the Multimap to append for all elements in thisMultimap
that are evaluated inkeyFunction
andvalueFunction
- Returns:
target
, which contains appended elements as a result of the transformation- Since:
- 10.0
-
collectValues
Returns a new multimap with the results of applying the specified function on each value of the source multimap. This method is also commonly called transform or map.e.g. return multimap.collectValues(new Function<Person, String>() { public String valueOf(Person person) { return person.getLastName(); } });
- Parameters:
function
- aFunction
to use for transformation- Returns:
Multimap
, which contains elements as a result of the transformation- Since:
- 6.0
-
collectValues
<V2,R extends MutableMultimap<K, R collectValuesV2>> (Function<? super V, ? extends V2> function, R target) Same as the collect method but uses the specified target multimap for the results.e.g. return multimap.collectValues(new Function<Person, String>() { public String valueOf(Person person) { return person.getLastName(); } }, FastListMultimap.<Integer, String>newMultimap());
- Parameters:
function
- aFunction
to use for transformationtarget
- the Multimap to append for all elements in thisMultimap
that are evaluated infunction
- Returns:
target
, which contains appended elements as a result of the transformation- Since:
- 6.0
-