eu.bandm.tools.ops

Interface Multimap<A,B>

All Superinterfaces:

Collection<Map.Entry<A,B>>, Iterable<Map.Entry<A,B>>, Relation<A,B>, Serializable, Set<Map.Entry<A,B>>

All Known Subinterfaces:

Multimap_checkedLeft<L,R>, Multimap_checkedRight<L,R>, SortedMultimap<A,B>

All Known Implementing Classes:

AbstractMultimap, CheckedMultimap_D, CheckedMultimap_R, CheckedMultimap_RD, ForwardMultimap, HashMultimap, IndexMultimap, MapMultimap

public interface Multimap<A,B>
extends Relation<A,B>, Set<Map.Entry<A,B>>, Serializable

A finite set of pairs. Pairs in a multimap are represented as instances of Map.Entry. The object returned by getKey() is called the left component of the pair; the object returned by getValue() is called the right component of the pair. null components are not supported.

The effect of attempting to change the right component by invoking setValue on a pair is unspecified. Implementations may either prohibit the operation by throwing UnsupportedOperationException or allow the operation but behave in an unspecified way afterwards.

Pairs in a multimap are considered equal if and only if both their left and right components are equal according to their respective equals methods. Such pairs are said to be equal componentwise. The implementations of Map.Entry returned by implementations must implement equals and hashCode accordingly.

Method Summary

Modifier and Type	Method and Description
boolean	add(A a, B b) Adds a pair to this this multimap.
boolean	contains(A a, B b)
boolean	containsUnchecked(Object a, Object b)
Set<A>	domain() Returns the set of left components of pairs in this multimap.
Set<B>	image(A a) Returns the set of right components of pairs with a given left component in this multimap.
Set<B>	imageAll(Collection<? extends A> a)
Set<B>	imageAllUnchecked(Collection<?> a)
Map<A,Set<B>>	imageMap()
Set<B>	imageUnchecked(Object a)
Set<A>	preimage(B b) Returns the set of left components of pairs with a given right component in this multimap.
Set<A>	preimageAll(Collection<? extends B> b)
Set<A>	preimageAllUnchecked(Collection<?> b)
Map<B,Set<A>>	preimageMap()
Set<A>	preimageUnchecked(Object b)
Set<B>	range() Returns the set of right components of pairs in this multimap.
boolean	remove(A a, B b) Removes a pair from this this multimap.
boolean	removeAllDomain(Collection<? extends A> c)
boolean	removeAllDomainUnchecked(Collection<?> c)
boolean	removeAllRange(Collection<? extends B> c)
boolean	removeAllRangeUnchecked(Collection<?> c)
boolean	removeDomain(A a) Removes all pairs with a given left component from this multimap.
boolean	removeRange(B b) Removes all pairs with a given right component from this multimap.
boolean	removeUnchecked(Object a, Object b)
boolean	retainAllDomain(Collection<? extends A> c)
boolean	retainAllDomainUnchecked(Collection<?> c)
boolean	retainAllRange(Collection<? extends B> c)
boolean	retainAllRangeUnchecked(Collection<?> c)

Methods inherited from interface eu.bandm.tools.ops.Relation

relates

Methods inherited from interface java.util.Set

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, iterator, remove, removeAll, retainAll, size, spliterator, toArray, toArray

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream

Methods inherited from interface java.lang.Iterable

forEach

Method Detail

add

boolean add(A a,
            B b)

Adds a pair to this this multimap. This operation must be stable: adding a pair that equals any pair contained in this multimap componentwise must not change this multimap.

Parameters:

a - the left component of the pair to add.

b - the right component of the pair to add.

Returns:

true if this multimap has been changed by this operation, false otherwise.

Throws:

NullPointerException - (optionally) if a or b is null.

IllegalArgumentException - (optionally) if a or b is null.

contains

boolean contains(A a,
                 B b)

containsUnchecked

boolean containsUnchecked(Object a,
                          Object b)

remove

boolean remove(A a,
               B b)

Removes a pair from this this multimap. Removing a pair that equals no pair contained in this multimap componentwise must not change this multimap.

Parameters:

a - the left component of the pair to remove.

b - the right component of the pair to remove.

Returns:

true if this multimap has been changed by this operation, false otherwise.

Throws:

NullPointerException - (optionally) if a or b is null.

IllegalArgumentException - (optionally) if a or b is null.

removeUnchecked

boolean removeUnchecked(Object a,
                        Object b)

removeDomain

boolean removeDomain(A a)

Removes all pairs with a given left component from this multimap. The effect of the implementation on this multimap must be equivalent to the following code:

 removeDomain(final A a) {
   for (B b : new HashSet<B>(range())) remove(a, b) ;
 }
 

Parameters:

a - the left component of all pairs to remove.

Returns:

true if this multimap has been changed by this operation, false otherwise.

Throws:

NullPointerException - (optionally) if a is null.

IllegalArgumentException - (optionally) if a is null.

removeRange

boolean removeRange(B b)

Removes all pairs with a given right component from this multimap. The effect of the implementation on this multimap must be equivalent to the following code:

 removeRange(final B b) {
   for (A a : new HashSet<A>(domain())) remove(a, b) ;
 }
 

Parameters:

b - the right component of all pairs to remove.

Returns:

true if this multimap has been changed by this operation, false otherwise.

Throws:

NullPointerException - (optionally) if b is null.

IllegalArgumentException - (optionally) if b is null.

removeAllDomain

boolean removeAllDomain(Collection<? extends A> c)

removeAllDomainUnchecked

boolean removeAllDomainUnchecked(Collection<?> c)

retainAllDomain

boolean retainAllDomain(Collection<? extends A> c)

retainAllDomainUnchecked

boolean retainAllDomainUnchecked(Collection<?> c)

removeAllRange

boolean removeAllRange(Collection<? extends B> c)

removeAllRangeUnchecked

boolean removeAllRangeUnchecked(Collection<?> c)

retainAllRange

boolean retainAllRange(Collection<? extends B> c)

retainAllRangeUnchecked

boolean retainAllRangeUnchecked(Collection<?> c)

domain

Set<A> domain()

Returns the set of left components of pairs in this multimap.

The returned set is backed by this multimap, such that changes to this multimap are reflected by the set. The behavior of modifications of this multimap concurrent to iteration of the set is unspecified.

If this multimap supports the removeDomain operation, then the returned set and its iterators must support the remove operation, and changes by these operations must be reflected by this multimap.

Returns:

the set of left components of pairs in this multimap.

range

Set<B> range()

Returns the set of right components of pairs in this multimap.

If this multimap supports the removeRange operation, then the returned set and its iterators must support the remove operation.

Returns:

the set of right components of pairs in this multimap.

image

Set<B> image(A a)

Returns the set of right components of pairs with a given left component in this multimap.

The returned set need not be modifiable. The behaviour of this multimap after successfully modifying the returned set is unspecified.

Parameters:

a - a left component.

Returns:

the set of right components of pairs with a left component that equals(a) in this multimap.

Throws:

NullPointerException - if a is null.

IllegalArgumentException - if a is null.

imageUnchecked

Set<B> imageUnchecked(Object a)

imageAll

Set<B> imageAll(Collection<? extends A> a)

imageAllUnchecked

Set<B> imageAllUnchecked(Collection<?> a)

imageMap

Map<A,Set<B>> imageMap()

preimage

Set<A> preimage(B b)

Returns the set of left components of pairs with a given right component in this multimap.

The returned set need not be modifiable. The behaviour of this multimap after successfully modifying the returned set is unspecified.

Parameters:

b - a right component.

Returns:

the set of left components of pairs with a right component that equals(b) in this multimap.

Throws:

NullPointerException - if b is null.

IllegalArgumentException - if b is null.

preimageUnchecked

Set<A> preimageUnchecked(Object b)

preimageAll

Set<A> preimageAll(Collection<? extends B> b)

preimageAllUnchecked

Set<A> preimageAllUnchecked(Collection<?> b)

preimageMap

Map<B,Set<A>> preimageMap()