Package io.timeandspace.collect.map

Interface ObjObjMap<K,V>

Type Parameters:

K - the type of keys maintained by this map

V - the type of mapped values

All Superinterfaces:

Map<K,V>

All Known Implementing Classes:

SmoothieMap

public interface ObjObjMap<K,V>
extends Map<K,V>

An extension of the Map interface. Notable additions and differences:

• null keys and values are explicitly prohibited. Attempt to query nulls via methods like get(Object) or containsValue(Object) are specified to throw a NullPointerException as well. In the Map interface, both aspects (rejecting nulls for storage and rejecting null queries) are optional.
• The notion of non-standard key and value equivalences is formalized in keyEquivalence() and valueEquivalence() methods.
• sizeAsLong() returns the exact size of the map if it exceeds Integer.MAX_VALUE.
• containsEntry(Object, Object)
• getInternalKey(K) allows to use the map as the vehicle for key interning.
• forEachWhile(BiPredicate)
• removeIf(BiPredicate)

Nested Class Summary

Nested classes/interfaces inherited from interface java.util.Map

Map.Entry<K extends Object,V extends Object>

Method Summary

Modifier and Type	Method	Description
void	clear()	Removes all of the mappings from this map.
@Nullable V	compute(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping).
@Nullable V	computeIfAbsent(K key, Function<? super K,? extends V> mappingFunction)	If the specified key is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this map unless null.
@Nullable V	computeIfPresent(K key, BiFunction<? super K,? super V,? extends V> remappingFunction)	If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.
boolean	containsEntry(Object key, Object value)	Returns true if this map contains a mapping of the given key and value.
boolean	containsKey(Object key)	Returns true if this map contains a mapping for the specified key.
boolean	containsValue(Object value)	Returns true if this map has one or more keys associated with the specified value.
ObjSet<Map.Entry<K,V>>	entrySet()	Returns a Set view of the mappings contained in this map.
boolean	equals(Object o)	Returns true if the other object is a Map; this map and the given map have the same size; and for all entries in the other map, containsEntry(e.getKey(), e.getValue()) called on this map returns true.
void	forEach(BiConsumer<? super K,? super V> action)	Performs the given action for each entry in this map until all entries have been processed or the action throws an exception.
boolean	forEachWhile(BiPredicate<? super K,? super V> predicate)	Checks the given predicate on each entry in this map until all entries have been processed or the predicate returns false for some entry, or throws an Exception.
@Nullable V	get(Object key)	Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.
@Nullable K	getInternalKey(K key)	Returns the key object held by this map internally and equivalent to the specified key, if there is one, or null if this map contains no mapping for the key.
V	getOrDefault(Object key, V defaultValue)	Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.
int	hashCode()	Returns a sum of the following expressions: keyEquivalence().hash(key) ^ valueEquivalence().hash(value) applied to all entries in this map.
Equivalence<K>	keyEquivalence()	Returns the equivalence strategy for keys for this map.
ObjSet<K>	keySet()	Returns a Set view of the keys contained in this map.
default long	mappingCount()	This method is an alias to sizeAsLong().
@Nullable V	merge(K key, V value, BiFunction<? super V,? super V,? extends V> remappingFunction)	If the specified key is not already associated with a value or is associated with null, associates it with the given value.
@Nullable V	put(K key, V value)	Associates the specified value with the specified key in this map.
void	putAll(Map<? extends K,? extends V> m)	Copies all of the mappings from the specified map to this map.
@Nullable V	putIfAbsent(K key, V value)	If the specified key is not already associated with a value, associates it with the given value and returns null, else returns the current value.
@Nullable V	remove(Object key)	Removes the mapping for a key from this map if it is present.
boolean	remove(Object key, Object value)	Removes the entry for the specified key only if it is currently mapped to the specified value.
boolean	removeIf(BiPredicate<? super K,? super V> filter)	Removes all of the entries of this map that satisfy the given predicate.
@Nullable V	replace(K key, V value)	Replaces the entry for the specified key only if it is currently mapped to some value.
boolean	replace(K key, V oldValue, V newValue)	Replaces the entry for the specified key only if currently mapped to the specified value.
void	replaceAll(BiFunction<? super K,? super V,? extends V> function)	Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception.
long	sizeAsLong()	Returns the number of entries in the map as a long value (not truncated to Integer.MAX_VALUE, if the map size exceeds it, as returned by the Map.size() method).
Equivalence<V>	valueEquivalence()	Returns the equivalence strategy for values for this map.
Collection<V>	values()	Returns a Collection view of the values contained in this map.

Methods inherited from interface java.util.Map

isEmpty, size

Method Detail

keyEquivalence

Equivalence<K> keyEquivalence()

Returns the equivalence strategy for keys for this map. All methods in the Map interface which are defined in terms of Object.equals(Object) equality of key objects use this Equivalence instead (including equals(java.lang.Object), hashCode(), and keySet()'s and entrySet()'s equals() and hashCode(), but excluding equals() and hashCode() of Map.Entry objects which can be obtained from the entrySet()).

Returns:

the equivalence strategy for keys for this map

valueEquivalence

Equivalence<V> valueEquivalence()

Returns the equivalence strategy for values for this map. All methods in the Map interface which defined in terms of Object.equals(Object) equality of value objects, such as containsValue(Object) and remove(Object, Object) use this Equivalence instead (including equals(java.lang.Object), hashCode(), and entrySet()'s equals() and hashCode(), but excluding equals() and hashCode() of Map.Entry objects which can be obtained from the entrySet()).

Returns:

the equivalence strategy for values for this map

sizeAsLong

long sizeAsLong()

Returns the number of entries in the map as a long value (not truncated to Integer.MAX_VALUE, if the map size exceeds it, as returned by the Map.size() method).

Returns:

the number of key-value mappings in this map

See Also:

Map.size(), mappingCount()

mappingCount

default long mappingCount()

This method is an alias to sizeAsLong(). It is defined for compatibility with ConcurrentHashMap.mappingCount().

Implementation Requirements:

The default implementation delegates to sizeAsLong().

Returns:

the number of key-value mappings in this map

See Also:

Map.size(), sizeAsLong()

containsKey

boolean containsKey(Object key)

Returns true if this map contains a mapping for the specified key. More formally, returns true if and only if this map contains a mapping for a key k such that the specified key and k are equivalent. (There can be at most one such mapping.)

Specified by:

containsKey in interface Map<K,V>

Parameters:

key - key whose presence in this map is to be tested

Returns:

true if this map contains a mapping for the specified key

Throws:

NullPointerException - if the given key is null

containsEntry

boolean containsEntry(Object key,
                      Object value)

Returns true if this map contains a mapping of the given key and value. More formally, this map should contain a mapping from a key k to a value v such that the specified key and k are equivalent with regard to keyEquivalence(), and the specified value and v are equivalent with regard to valueEquivalence(). (There can be at most one such mapping.)

Parameters:

key - the key of the mapping to check presence of

value - the value of the mapping to check presence of

Returns:

true if this map contains the specified mapping, false otherwise

Throws:

NullPointerException - if the given key or value is null

getInternalKey

@Nullable K getInternalKey(K key)

Returns the key object held by this map internally and equivalent to the specified key, if there is one, or null if this map contains no mapping for the key.

This method could be used to deduplicate objects in the application, to reduce the memory footprint and make the application to conform to the "most objects die young" hypothesis that most GC algorithms are optimized for. This method is functionally similar to String.intern() and Guava's Interner, but allows to piggy-back a map data structure which may already exist in an application.

keySet().getInternal(key) delegates to this method.

Parameters:

key - the key whose equivalent held by this map internally is to be returned

Returns:

the map-internal equivalent of the specified key, or null if the map contains no mapping for the specified key

get

@Nullable V get(Object key)

Returns the value to which the specified key is mapped, or null if this map contains no mapping for the key.

More formally, if this map contains a mapping from a key k to a value v such that the specified key and k are equivalent, then this method returns v; otherwise it returns null. (There can be at most one such mapping.)

Specified by:

get in interface Map<K,V>

Parameters:

key - the key whose associated value is to be returned

Returns:

the value to which the specified key is mapped, or null if this map contains no mapping for the key

Throws:

NullPointerException - if the given key is null

getOrDefault

V getOrDefault(Object key,
               V defaultValue)

Returns the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key.

Specified by:

getOrDefault in interface Map<K,V>

Parameters:

key - the key whose associated value is to be returned

defaultValue - the default mapping of the key

Returns:

the value to which the specified key is mapped, or defaultValue if this map contains no mapping for the key

Throws:

NullPointerException - if the given key is null

put

@Nullable V put(K key,
                V value)

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced by the specified value. (A map m is said to contain a mapping for a key k if and only if m.containsKey(k) would return true.)

Specified by:

put in interface Map<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with key, or null if there was no mapping for key

Throws:

NullPointerException - if the given key or value is null

putIfAbsent

@Nullable V putIfAbsent(K key,
                        V value)

If the specified key is not already associated with a value, associates it with the given value and returns null, else returns the current value.

Specified by:

putIfAbsent in interface Map<K,V>

Parameters:

key - key with which the specified value is to be associated

value - value to be associated with the specified key

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key

Throws:

NullPointerException - if the given key or value is null

replace

@Nullable V replace(K key,
                    V value)

Replaces the entry for the specified key only if it is currently mapped to some value.

Specified by:

replace in interface Map<K,V>

Parameters:

key - key with which the specified value is associated

value - value to be associated with the specified key

Returns:

the previous value associated with the specified key, or null if there was no mapping for the key.

Throws:

NullPointerException - if the given key or value is null

replace

boolean replace(K key,
                V oldValue,
                V newValue)

Replaces the entry for the specified key only if currently mapped to the specified value. Values are compared using valueEquivalence().

Specified by:

replace in interface Map<K,V>

Parameters:

key - key with which the specified value is associated

oldValue - value expected to be associated with the specified key

newValue - value to be associated with the specified key

Returns:

true if the value was replaced

Throws:

NullPointerException - if the given key, oldValue or newValue is null

computeIfPresent

@Nullable V computeIfPresent(K key,
                             BiFunction<? super K,? super V,? extends V> remappingFunction)

If the value for the specified key is present and non-null, attempts to compute a new mapping given the key and its current mapped value.

If the function returns null, the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Specified by:

computeIfPresent in interface Map<K,V>

Parameters:

key - key with which the specified value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if none

Throws:

NullPointerException - if the given key or remappingFunction is null

remove

@Nullable V remove(Object key)

Removes the mapping for a key from this map if it is present. More formally, if this map contains a mapping from key k to value v such that the specified key and k are equivalent, that mapping is removed. (The map can contain at most one such mapping.)

Returns the value to which this map previously associated the key, or null if the map contained no mapping for the key.

The map will not contain a mapping for the specified key once the call returns.

Specified by:

remove in interface Map<K,V>

Parameters:

key - key whose mapping is to be removed from the map

Returns:

the previous value associated with key, or null if there was no mapping for key

Throws:

NullPointerException - if the given key is null

remove

boolean remove(Object key,
               Object value)

Removes the entry for the specified key only if it is currently mapped to the specified value. Values are compared using valueEquivalence().

Specified by:

remove in interface Map<K,V>

Parameters:

key - key with which the specified value is associated

value - value expected to be associated with the specified key

Returns:

true if the value was removed

Throws:

NullPointerException - if the given key or value is null

computeIfAbsent

@Nullable V computeIfAbsent(K key,
                            Function<? super K,? extends V> mappingFunction)

If the specified key is not already associated with a value, attempts to compute its value using the given mapping function and enters it into this map unless null.

If the function returns null no mapping is recorded. If the function itself throws an (unchecked) exception, the exception is rethrown, and no mapping is recorded. The most common usage is to construct a new object serving as an initial mapped value or memoized result, as in:

 
 map.computeIfAbsent(key, k -> new Value(f(k)));
 

Or to implement a multi-value map, Map<K,Collection<V>>, supporting multiple values per key:

 
 map.computeIfAbsent(key, k -> new HashSet<V>()).add(v);
 

Specified by:

computeIfAbsent in interface Map<K,V>

Parameters:

key - key with which the specified value is to be associated

mappingFunction - the function to compute a value

Returns:

the current (existing or computed) value associated with the specified key, or null if the computed value is null

Throws:

NullPointerException - if the given key or mappingFunction is null

compute

@Nullable V compute(K key,
                    BiFunction<? super K,? super V,? extends V> remappingFunction)

Attempts to compute a mapping for the specified key and its current mapped value (or null if there is no current mapping). For example, to either create or append a String msg to a value mapping:

 
 map.compute(key, (k, v) -> (v == null) ? msg : v.concat(msg))

(Method merge() is often simpler to use for such purposes.)

If the function returns null, the mapping is removed (or remains absent if initially absent). If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Specified by:

compute in interface Map<K,V>

Parameters:

key - key with which the specified value is to be associated

remappingFunction - the function to compute a value

Returns:

the new value associated with the specified key, or null if none

Throws:

NullPointerException - if the given key or remappingFunction is null

merge

@Nullable V merge(K key,
                  V value,
                  BiFunction<? super V,? super V,? extends V> remappingFunction)

If the specified key is not already associated with a value or is associated with null, associates it with the given value. Otherwise, replaces the associated value with the results of the given remapping function, or removes if the result is null. This method may be of use when combining multiple mapped values for a key. For example, to either create or append a String msg to a value mapping:

 
 map.merge(key, msg, String::concat)
 

If the function returns null the mapping is removed. If the function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged.

Specified by:

merge in interface Map<K,V>

Parameters:

key - key with which the resulting value is to be associated

value - the value to be merged with the existing value associated with the key or, if no existing value is associated with the key, to be associated with the key

remappingFunction - the function to recompute a value if present

Returns:

the new value associated with the specified key, or null if no value is associated with the key

Throws:

NullPointerException - if the given key, value or remappingFunction is null

forEach

void forEach(BiConsumer<? super K,? super V> action)

Performs the given action for each entry in this map until all entries have been processed or the action throws an exception. Actions are performed in the order of entry set iteration. Exceptions thrown by the action are relayed to the caller.

The entries will be processed in the same order as they appear the entry set's iterator and forEachWhile(BiPredicate).

Specified by:

forEach in interface Map<K,V>

Parameters:

action - The action to be performed for each entry

Throws:

NullPointerException - if the specified action is null

ConcurrentModificationException - if any structural modification of the map (new entry insertion or an entry removal) is detected during iteration

See Also:

forEachWhile(BiPredicate)

forEachWhile

boolean forEachWhile(BiPredicate<? super K,? super V> predicate)

Checks the given predicate on each entry in this map until all entries have been processed or the predicate returns false for some entry, or throws an Exception. Exceptions thrown by the predicate are relayed to the caller.

The entries will be processed in the same order as they appear in the entry set's iterator and forEach(BiConsumer).

If the map is empty, this method returns true immediately.

Parameters:

predicate - the predicate to be checked for each entry

Returns:

true if the map is empty, or if the predicate returned true for all entries of the map, false if the predicate returned false for some entry

Throws:

NullPointerException - if the specified predicate is null

ConcurrentModificationException - if any structural modification of the map (new entry insertion or an entry removal) is detected during iteration

See Also:

forEach(BiConsumer)

replaceAll

void replaceAll(BiFunction<? super K,? super V,? extends V> function)

Replaces each entry's value with the result of invoking the given function on that entry until all entries have been processed or the function throws an exception. Exceptions thrown by the function are relayed to the caller.

Specified by:

replaceAll in interface Map<K,V>

Parameters:

function - the function to apply to each entry

Throws:

NullPointerException - if the specified function is null

ConcurrentModificationException - if any structural modification of the map (new entry insertion or an entry removal) is detected during iteration

containsValue

boolean containsValue(Object value)

Returns true if this map has one or more keys associated with the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that valueEquivalence().equivalent(value, v) == true. This operation requires time linear in the map size.

Specified by:

containsValue in interface Map<K,V>

Parameters:

value - value whose presence in this map is to be tested

Returns:

true if this map maps one or more keys to the specified value

putAll

void putAll(Map<? extends K,? extends V> m)

Copies all of the mappings from the specified map to this map. The effect of this call is equivalent to that of calling put(k, v) on this map once for each mapping from key k to value v in the specified map. The behavior of this operation is undefined if the specified map is modified while the operation is in progress.

Specified by:

putAll in interface Map<K,V>

Parameters:

m - mappings to be stored in this map

Throws:

NullPointerException - if the specified map is null

clear

void clear()

Removes all of the mappings from this map. The map will be empty after this call returns.

Specified by:

clear in interface Map<K,V>

Throws:

ConcurrentModificationException - if any structural modification of the map (new entry insertion or an entry removal) is detected during operation

removeIf

boolean removeIf(BiPredicate<? super K,? super V> filter)

Removes all of the entries of this map that satisfy the given predicate. Errors or runtime exceptions thrown during iteration or by the predicate are relayed to the caller.

Note the order in which this method visits entries may be different from the iteration and forEach(BiConsumer) order.

Parameters:

filter - a predicate which returns true for entries to be removed

Returns:

true if any entries were removed

Throws:

NullPointerException - if the specified filter is null

ConcurrentModificationException - if any structural modification of the map (new entry insertion or an entry removal) is detected during iteration

keySet

ObjSet<K> keySet()

Returns a Set view of the keys contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.

If a structural modification of the map (new entry insertion or an entry removal) is detected while an iteration over the set is in progress (except through the iterator's own remove operation), ConcurrentModificationException is thrown.

The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove() (optionally), Set.remove(java.lang.Object), Set.removeAll(java.util.Collection<?>), Set.retainAll(java.util.Collection<?>), and Set.clear() operations.

Set.remove(java.lang.Object), Set.contains(java.lang.Object), and Set.containsAll(java.util.Collection<?>) operations on the returned set as well as key set's own equals() and hashCode() respect the map's keyEquivalence(). When this map has a custom keyEquivalence(), equals() on the key set works as follows: another object is considered equal to the key set if it is a Set which has the same size as this map and for all elements in another set, keySet.contains(elementOfAnotherSet) returns true. hashCode() on the key set returns a sum of results of calls to Equivalence.hash(T) on all elements in the key set.

The key set does not support the Set.add(E) and Set.addAll(java.util.Collection<? extends E>) operations.

The set is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same set.

Specified by:

keySet in interface Map<K,V>

Returns:

a set view of the keys contained in this map

values

Collection<V> values()

Returns a Collection view of the values contained in this map. The collection is backed by the map, so changes to the map are reflected in the collection, and vice-versa.

If a structural modification of the map (new entry insertion or an entry removal) is detected while an iteration over the collection is in progress (except through the iterator's own remove operation), ConcurrentModificationException is thrown.

The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove() (optionally), Collection.remove(java.lang.Object), Collection.removeAll(java.util.Collection<?>), Collection.retainAll(java.util.Collection<?>) and Collection.clear() operations.

Collection.remove(java.lang.Object), Collection.contains(java.lang.Object), and Collection.containsAll(java.util.Collection<?>) on the returned collection respect the map's valueEquivalence().

The values collection does not support the add or addAll operations.

The collection is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same collection.

Specified by:

values in interface Map<K,V>

Returns:

a collection view of the values contained in this map

entrySet

ObjSet<Map.Entry<K,V>> entrySet()

Returns a Set view of the mappings contained in this map. The set is backed by the map, so changes to the map are reflected in the set, and vice-versa.

If a structural modification of the map (new entry insertion or an entry removal) is detected while an iteration over the set is in progress (except through the iterator's own remove operation), ConcurrentModificationException is thrown.

The set supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove() (optionally), Set.remove(java.lang.Object), Set.removeAll(java.util.Collection<?>), Set.retainAll(java.util.Collection<?>), and Set.clear() operations.

Set.remove(java.lang.Object), Set.contains(java.lang.Object), and Set.containsAll(java.util.Collection<?>) operations on the returned set as well as entry set's own equals() and hashCode() respect the map's keyEquivalence() and valueEquivalence(), but the implementations of equals() and hashCode() for the Map.Entry objects which can be obtained from the set use built-in Java object equality and hash code for the map's keys and values.

When this map has a custom keyEquivalence() or valueEquivalence(), equals() on the entry set works as follows: another object is considered equal to the entry set if it is a Set which has the same size as this map; all elements in another set are Map.Entry objects; and for all the entries in another set, thisMap.containsEntry(entryFromAnotherSet.getKey(), entryFromAnotherSet.getValue()) returns true. hashCode() on the entry set is the same as on the map itself, see hashCode().

The entry set does not support the Set.add(E) and Set.addAll(java.util.Collection<? extends E>) operations.

The set is created the first time this method is called, and returned in response to all subsequent calls. No synchronization is performed, so there is a slight chance that multiple calls to this method will not all return the same set.

Specified by:

entrySet in interface Map<K,V>

Returns:

a set view of the mappings contained in this map

equals

boolean equals(Object o)

Returns true if the other object is a Map; this map and the given map have the same size; and for all entries in the other map, containsEntry(e.getKey(), e.getValue()) called on this map returns true.

Note that the specification above means that equals() depends on keyEquivalence() and valueEquivalence() of this map, if they are custom. This may be inconsistent with the general Map.equals(java.lang.Object) contract.

Specified by:

equals in interface Map<K,V>

Overrides:

equals in class Object

hashCode

int hashCode()

Returns a sum of the following expressions: keyEquivalence().hash(key) ^ valueEquivalence().hash(value) applied to all entries in this map. Note that if this map has a custom keyEquivalence() or valueEquivalence(), the resulting hash code may be inconsistent with the general Map.hashCode() contract.

Specified by:

hashCode in interface Map<K,V>

Overrides:

hashCode in class Object