org.jjoost.collections.bimaps
Class AbstractBiMap<K,V,M extends AnyMap<K,V>,I extends AnyMap<V,K>>

java.lang.Object
  org.jjoost.collections.bimaps.AbstractBiMap<K,V,M,I>

All Implemented Interfaces:

java.io.Serializable, AnyMap<K,V>, AnyReadMap<K,V>

Direct Known Subclasses:

BiMap, BiMapListToList, BiMapListToMany, BiMapManyToList, BiMapManyToMany, BiMapManyToOne, BiMapOneToMany, BiMapOneToOne

public abstract class AbstractBiMap<K,V,M extends AnyMap<K,V>,I extends AnyMap<V,K>>
extends java.lang.Object
implements AnyMap<K,V>

See Also:

Serialized Form

Method Summary

boolean	add(K key, V val) Attempt to add the pair to the map, returning false if it could not be added, and true otherwise.
int	clear() Clears the map, returning the number of elements removed from it.
java.util.Iterator<java.util.Map.Entry<K,V>>	clearAndReturn() Clears the map, returning the entries removed from it.
boolean	contains(K key) Returns true iff a key occurs in the map which is equal to the parameter, as determined by the map's definition of equality.
boolean	contains(K key, V val) Returns true iff a (key,value) pair occurs in the map that is equal to those provided, as determined by the map's definition(s) of equality.
int	count(K key) Returns the number of occurrences of keys present in the map that are equal to the one provided, as determined by the map's definition of equality.
int	count(K key, V val) Returns the number of occurrences of (key, value) pairs present in the map that are equal to the one provided, as determined by the map's definition(s) of equality.
java.lang.Iterable<java.util.Map.Entry<K,V>>	entries(K key) Returns an Iterable over all key->value maplets in the map whose key is equal to the one provided, as determined by the map's definition of equality.
V	first(K key) Returns the value associated with the first key that is equal to the one provided, as determined by the map's definition of equality.
AnyMap<V,K>	inverse() Returns a map representing the inverse function of this map.
boolean	isEmpty() Returns true iff the map is empty
java.util.List<V>	list(K key) Returns a List of all values in the map which are mapped to by the provided key, as determined by the map's definition of equality.
boolean	permitsDuplicateKeys() Returns true if a key can map to more than one value
V	put(K key, V val) Ensures that the provided key binds to the provided value at least once; depending on the underlying implementation this may remove any existing key->value pairs where the key is equal to the one provided (Map), the key and value are both equal (MultiMap), or simply append this key to all existing maplets regardless of their equality (ListMap).
V	putIfAbsent(K key, V val) Attempts to bind the provided key to the provided value.
int	remove(K key) Removes all occurrences of the provided key from domain of the map, returning an integer representing the total number of items removed
int	remove(K key, V val) Removes all occurrences of the provided key->value pair from the map, returning an integer representing the total number of items removed
java.lang.Iterable<java.util.Map.Entry<K,V>>	removeAndReturn(K key) Removes all occurrences of the provided key from domain of the map, returning the entries removed
java.lang.Iterable<java.util.Map.Entry<K,V>>	removeAndReturn(K key, V val) Removes all occurrences of the provided key->value pair from the map, returning the entries removed
V	removeAndReturnFirst(K key) Removes all occurrences of the provided key from domain of the map, returning the first such value removed, or null if none
void	shrink() Attempts to make the map use less memory, if possible.
int	totalCount() Return an integer representing the total number of maplets (i.e.
int	uniqueKeyCount() Return an integer representing the number of unique keys in the domain of the map
AnySet<V>	values() Returns a set representing the range of the map.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.jjoost.collections.AnyMap

copy, entries, keys, values

Method Detail

clear

public int clear()

Description copied from interface: AnyMap

Clears the map, returning the number of elements removed from it. In a concurrent map, whilst there is no guarantee that the map will be empty when this method returns if it is being concurrently modified, the number will accurately convey the number of items removed.

Specified by:

clear in interface AnyMap<K,V>

Returns:

the int

clearAndReturn

public java.util.Iterator<java.util.Map.Entry<K,V>> clearAndReturn()

Description copied from interface: AnyMap

Clears the map, returning the entries removed from it. In a concurrent map the Iterator will accurately represent the elements that are removed from the map; however the Iterator must be exhausted for the clear operation to be guaranteed to have completed.

Specified by:

clearAndReturn in interface AnyMap<K,V>

Returns:

the iterator< entry< k, v>>

inverse

public AnyMap<V,K> inverse()

Description copied from interface: AnyMap

Returns a map representing the inverse function of this map. This operation will typically be expensive unless the map is a BiMap in which case the action is trivial. The method may not return a map of the same type as the one it is called on (although typically this will be the case, and should happen wherever possible).

Specified by:

inverse in interface AnyMap<K,V>

Returns:

the inverse map/function of the one called upon

add

public boolean add(K key,
                   V val)

Description copied from interface: AnyMap

Attempt to add the pair to the map, returning false if it could not be added, and true otherwise. In a ListMap the return value will always be true; however in a MultiMap it will be false, and hence the map remain unmodified, if a pair whose key and value are both equal to the ones provided (as determined by the map's definitions of equality) is already present; and in a Map it will be false if a pair whose key is equal to the one provided is already present. When the value of the pair is inequal to null, this is equivalent to put(key, value) == null

Specified by:

add in interface AnyMap<K,V>

Parameters:

key - key to insert

val - value to insert

Returns:

true if the map was modified, false otherwise

put

public V put(K key,
             V val)

Description copied from interface: AnyMap

Ensures that the provided key binds to the provided value at least once; depending on the underlying implementation this may remove any existing key->value pairs where the key is equal to the one provided (Map), the key and value are both equal (MultiMap), or simply append this key to all existing maplets regardless of their equality (ListMap). If any pair is removed as a result of this action, the value of that pair is returned.

Specified by:

put in interface AnyMap<K,V>

Parameters:

key - the key

val - the val

Returns:

the value of any maplet removed as a result of this action

putIfAbsent

public V putIfAbsent(K key,
                     V val)

Description copied from interface: AnyMap

Attempts to bind the provided key to the provided value. If the key does not occur in the map then the value will be associated with it and null returned. If the key occurs in the map and is bound to a different value then a Map will return this value, whereas both MultiMap and ListMap will insert the new pair and return null. If the key->value pair is present in the map then all maps will return a value already associated with the key (in both Map and MultiMap there will be precisely one such value)

Specified by:

putIfAbsent in interface AnyMap<K,V>

Parameters:

key - the key

val - the val

Returns:

implementation dependent

remove

public int remove(K key,
                  V val)

Description copied from interface: AnyMap

Removes all occurrences of the provided key->value pair from the map, returning an integer representing the total number of items removed

Specified by:

remove in interface AnyMap<K,V>

Parameters:

key - the key

val - the val

Returns:

the number removed

remove

public int remove(K key)

Description copied from interface: AnyMap

Removes all occurrences of the provided key from domain of the map, returning an integer representing the total number of items removed

Specified by:

remove in interface AnyMap<K,V>

Parameters:

key - remove

Returns:

the number removed

removeAndReturn

public java.lang.Iterable<java.util.Map.Entry<K,V>> removeAndReturn(K key,
                                                                    V val)

Description copied from interface: AnyMap

Removes all occurrences of the provided key->value pair from the map, returning the entries removed

Specified by:

removeAndReturn in interface AnyMap<K,V>

Parameters:

key - key to remove

val - value to remove

Returns:

entries removed

removeAndReturn

public java.lang.Iterable<java.util.Map.Entry<K,V>> removeAndReturn(K key)

Description copied from interface: AnyMap

Removes all occurrences of the provided key from domain of the map, returning the entries removed

Specified by:

removeAndReturn in interface AnyMap<K,V>

Parameters:

key - key to remove

Returns:

entries removed

removeAndReturnFirst

public V removeAndReturnFirst(K key)

Description copied from interface: AnyMap

Removes all occurrences of the provided key from domain of the map, returning the first such value removed, or null if none

Specified by:

removeAndReturnFirst in interface AnyMap<K,V>

Parameters:

key - the key to remove

Returns:

the value associated with the first key removed, or null if none

shrink

public void shrink()

Description copied from interface: AnyMap

Attempts to make the map use less memory, if possible.

Specified by:

shrink in interface AnyMap<K,V>

contains

public boolean contains(K key,
                        V val)

Description copied from interface: AnyReadMap

Returns true iff a (key,value) pair occurs in the map that is equal to those provided, as determined by the map's definition(s) of equality.

Specified by:

contains in interface AnyReadMap<K,V>

Parameters:

key - the key

val - the val

Returns:

true, if present

contains

public boolean contains(K key)

Description copied from interface: AnyReadMap

Returns true iff a key occurs in the map which is equal to the parameter, as determined by the map's definition of equality.

Specified by:

contains in interface AnyReadMap<K,V>

Parameters:

key - find

Returns:

true, if present

count

public int count(K key,
                 V val)

Description copied from interface: AnyReadMap

Returns the number of occurrences of (key, value) pairs present in the map that are equal to the one provided, as determined by the map's definition(s) of equality.

Specified by:

count in interface AnyReadMap<K,V>

Parameters:

key - the key

val - the val

Returns:

number of occurrences

count

public int count(K key)

Description copied from interface: AnyReadMap

Returns the number of occurrences of keys present in the map that are equal to the one provided, as determined by the map's definition of equality.

Specified by:

count in interface AnyReadMap<K,V>

Parameters:

key - the key

Returns:

number of occurrences

entries

public java.lang.Iterable<java.util.Map.Entry<K,V>> entries(K key)

Description copied from interface: AnyReadMap

Returns an Iterable over all key->value maplets in the map whose key is equal to the one provided, as determined by the map's definition of equality.

Specified by:

entries in interface AnyReadMap<K,V>

Parameters:

key - find

Returns:

maplets with the provided key

first

public V first(K key)

Description copied from interface: AnyReadMap

Returns the value associated with the first key that is equal to the one provided, as determined by the map's definition of equality. Returns null if no matching key is found.

Specified by:

first in interface AnyReadMap<K,V>

Parameters:

key - the key

Returns:

the value associated with the first matching key

isEmpty

public boolean isEmpty()

Description copied from interface: AnyReadMap

Returns true iff the map is empty

Specified by:

isEmpty in interface AnyReadMap<K,V>

Returns:

true, if empty

list

public java.util.List<V> list(K key)

Description copied from interface: AnyReadMap

Returns a List of all values in the map which are mapped to by the provided key, as determined by the map's definition of equality. This list should be constructed "eagerly" and should be a consistent snapshot of the values valid at some point between the method being called and it returning.

Specified by:

list in interface AnyReadMap<K,V>

Parameters:

key - the key

Returns:

the list< v>

permitsDuplicateKeys

public boolean permitsDuplicateKeys()

Description copied from interface: AnyReadMap

Returns true if a key can map to more than one value

Specified by:

permitsDuplicateKeys in interface AnyReadMap<K,V>

Returns:

true, if keys can map to more than one value

totalCount

public int totalCount()

Description copied from interface: AnyReadMap

Return an integer representing the total number of maplets (i.e. counting all occurrences of each key) in the map

Specified by:

totalCount in interface AnyReadMap<K,V>

Returns:

the total number of maplets

uniqueKeyCount

public int uniqueKeyCount()

Description copied from interface: AnyReadMap

Return an integer representing the number of unique keys in the domain of the map

Specified by:

uniqueKeyCount in interface AnyReadMap<K,V>

Returns:

number of unique keys

values

public AnySet<V> values()

Description copied from interface: AnyMap

Returns a set representing the range of the map. Operations on this set will typically be expensive (O(n) where n is the size of the map).

Specified by:

values in interface AnyMap<K,V>

Specified by:

values in interface AnyReadMap<K,V>

Returns:

the range of the map