Package org.eclipse.collections.api.multimap

Interface Multimap<K,V>

Type Parameters:

K - the type of keys used

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

public interface Multimap<K,V>

This collection is a type of 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 Type	Method	Description
<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>> R	collectKeyMultiValues(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>> R	collectKeysValues(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.
<V2> Multimap<K,V2>	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>> R	collectValues(Function<? super V,? extends V2> function, R target)	Same as the collect method but uses the specified target multimap for the results.
boolean	containsKey(java.lang.Object key)	Returns true if any values are mapped to the specified key.
boolean	containsKeyAndValue(java.lang.Object key, java.lang.Object value)	Returns true if the specified key-value pair is mapped.
boolean	containsValue(java.lang.Object value)	Returns true if any key is mapped to the specified value.
boolean	equals(java.lang.Object obj)	Compares the specified object with this Multimap for equality.
Multimap<V,K>	flip()	Given a Multimap from Domain -> Range return a multimap from Range -> Domain.
void	forEachKey(Procedure<? super K> procedure)	Calls the procedure with each key.
void	forEachKeyMultiValues(Procedure2<? super K,? super java.lang.Iterable<V>> procedure)	Calls the procedure with each key-Iterable[value].
void	forEachKeyValue(Procedure2<? super K,? super V> procedure)	Calls the procedure with each key-value pair.
void	forEachValue(Procedure<? super V> procedure)	Calls the procedure with each value.
RichIterable<V>	get(K key)	Returns a view of all values associated with the given key.
int	hashCode()	Returns the hash code for this Multimap.
boolean	isEmpty()	Returns true if there are no entries.
Bag<K>	keyBag()	Returns a Bag of keys with the count corresponding to the number of mapped values.
RichIterable<Pair<K,RichIterable<V>>>	keyMultiValuePairsView()	Returns a lazy view of the pair of a key and and a lazy view of the values mapped to that key.
SetIterable<K>	keySet()	Returns a unmodifiable SetIterable of keys with O(1) complexity.
RichIterable<K>	keysView()	Returns a lazy view of the unique keys.
RichIterable<Pair<K,V>>	keyValuePairsView()	Returns a lazy view of all of the key/value pairs.
RichIterable<RichIterable<V>>	multiValuesView()	Returns an unmodifiable view of all of the values mapped to each key.
Multimap<K,V>	newEmpty()	Creates a new instance of the same implementation type, using the default capacity and growth parameters.
boolean	notEmpty()	Returns true if there is at least one entry.
Multimap<K,V>	rejectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate)	Returns all elements of the source multimap that don't satisfy the predicate.
<R extends MutableMultimap<K,V>> R	rejectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate, R target)	Same as the reject method but uses the specified target multimap for the results.
Multimap<K,V>	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>> R	rejectKeysValues(Predicate2<? super K,? super V> predicate, R target)	Same as the reject method but uses the specified target multimap for the results.
Multimap<K,V>	selectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate)	Returns all elements of the source multimap that satisfies the predicate.
<R extends MutableMultimap<K,V>> R	selectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate, R target)	Same as the select method but uses the specified target multimap for the results.
Multimap<K,V>	selectKeysValues(Predicate2<? super K,? super V> predicate)	Returns all elements of the source multimap that satisfies the predicate.
<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.
int	size()	Returns the number of key-value entry pairs.
int	sizeDistinct()	Returns the number of distinct keys.
ImmutableMultimap<K,V>	toImmutable()	Returns an immutable copy of this Multimap if it is not already immutable.
MutableMap<K,RichIterable<V>>	toMap()	Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.
<R extends java.util.Collection<V>> MutableMap<K,R>	toMap(Function0<R> collectionFactory)	Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.
MutableMultimap<K,V>	toMutable()	Returns a mutable copy of this Multimap.
RichIterable<V>	valuesView()	Returns a lazy flattened view of all the values.

Method Detail

newEmpty

Multimap<K,V> newEmpty()

Creates a new instance of the same implementation type, using the default capacity and growth parameters.

isEmpty

boolean isEmpty()

Returns true if there are no entries.

notEmpty

boolean notEmpty()

Returns true if there is at least one entry.

forEachValue

void forEachValue(Procedure<? super V> procedure)

Calls the procedure with each value.

Given a Multimap with the contents:

{"key1" : ["val1", "val2", "val2"], "key2" : ["val3"]}

The given procedure would be invoked with the parameters:

["val1", "val2", "val2", "val3"]

forEachKey

void forEachKey(Procedure<? super K> procedure)

Calls the procedure 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

void forEachKeyValue(Procedure2<? super K,? super V> procedure)

Calls the procedure 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

void forEachKeyMultiValues(Procedure2<? super K,? super java.lang.Iterable<V>> procedure)

Calls the procedure 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

boolean containsKey(java.lang.Object key)

Returns true if any values are mapped to the specified key.

Parameters:

key - the key to search for

containsValue

boolean containsValue(java.lang.Object value)

Returns true if any key is mapped to the specified value.

Parameters:

value - the value to search for

containsKeyAndValue

boolean containsKeyAndValue(java.lang.Object key,
                            java.lang.Object value)

Returns true if the specified key-value pair is mapped.

Parameters:

key - the key to search for

value - the value to search for

get

RichIterable<V> get(K key)

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 a unmodifiable SetIterable of keys with O(1) complexity.

keyBag

Bag<K> keyBag()

Returns a Bag of keys with the count corresponding to the number of mapped values.

multiValuesView

RichIterable<RichIterable<V>> multiValuesView()

Returns an unmodifiable view of all of 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 and a lazy view of the values mapped to that key.

keyValuePairsView

RichIterable<Pair<K,V>> keyValuePairsView()

Returns a lazy view of all of the key/value pairs.

toMap

MutableMap<K,RichIterable<V>> toMap()

Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.

toMap

<R extends java.util.Collection<V>> MutableMap<K,R> toMap(Function0<R> collectionFactory)

Returns a new MutableMap of keys from this Multimap to the mapped values as a RichIterable.

Parameters:

collectionFactory - used to create the collections that hold the values and affects the return type

equals

boolean equals(java.lang.Object obj)

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.

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

Overrides:

hashCode in class java.lang.Object

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 is Serializable.

flip

Multimap<V,K> flip()

Given a Multimap from Domain -> Range return a multimap from Range -> Domain.

Since:

6.0

selectKeysValues

Multimap<K,V> selectKeysValues(Predicate2<? super K,? super V> predicate)

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 - a Predicate2 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 - a Predicate2 to use as the select criteria

target - the Multimap to append to for all elements in this Multimap that satisfy the predicate

Returns:

target, which contains appended elements as a result of the select criteria

Since:

6.0

rejectKeysValues

Multimap<K,V> rejectKeysValues(Predicate2<? super K,? super V> predicate)

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 - a Predicate2 to use as the reject criteria

Returns:

Multimap, which contains elements that don't satisfy the predicate

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 - a Predicate2 to use as the reject criteria

target - the Multimap to append to for all elements in this Multimap that don't satisfy the predicate

Returns:

target, which contains appended elements that don't satisfy the predicate

Since:

6.0

selectKeysMultiValues

Multimap<K,V> selectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate)

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 - a Predicate2 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 java.lang.Iterable<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 - a Predicate2 to use as the select criteria

target - the Multimap to append to for all elements in this Multimap that satisfy the predicate

Returns:

target, which contains appended elements as a result of the select criteria

Since:

6.0

rejectKeysMultiValues

Multimap<K,V> rejectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<V>> predicate)

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 - a Predicate2 to use as the reject criteria

Returns:

Multimap, which contains elements that don't satisfy the predicate

Since:

6.0

rejectKeysMultiValues

<R extends MutableMultimap<K,V>> R rejectKeysMultiValues(Predicate2<? super K,? super java.lang.Iterable<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 - a Predicate2 to use as the reject criteria

target - the Multimap to append to for all elements in this Multimap that don't satisfy the predicate

Returns:

target, which contains appended elements that don't satisfy the predicate

Since:

6.0

collectKeysValues

<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. 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 - a Function2 to use for transformation

Returns:

Multimap, which contains elements as a result of the transformation

Since:

6.0

collectKeysValues

<K2,V2,R extends MutableMultimap<K2,V2>> R collectKeysValues(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 - a Function2 to use for transformation

target - the Multimap to append for all elements in this Multimap that are evaluated in function

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);
 

Parameters:

keyFunction - Function to use transformation to get the key

valueFunction - Function to use transformation to get the values

Returns:

a new Multimap, which contains elements as a result of the transformation

Since:

10.0

collectKeyMultiValues

<K2,V2,R extends MutableMultimap<K2,V2>> R collectKeyMultiValues(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 key

valueFunction - Function to use transformation to get the values

target - the Multimap to append for all elements in this Multimap that are evaluated in keyFunction and valueFunction

Returns:

target, which contains appended elements as a result of the transformation

Since:

10.0

collectValues

<V2> Multimap<K,V2> 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. 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 - a Function to use for transformation

Returns:

Multimap, which contains elements as a result of the transformation

Since:

6.0

collectValues

<V2,R extends MutableMultimap<K,V2>> R collectValues(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 - a Function to use for transformation

target - the Multimap to append for all elements in this Multimap that are evaluated in function

Returns:

target, which contains appended elements as a result of the transformation

Since:

6.0