Interface IMultiLookup<Key,Value>
-
- All Known Subinterfaces:
IMultiLookupAbstract<Key,Value,Bucket>
,IMultiLookupAbstract.ToMultisetsAbstract<Key,Value>
,IMultiLookupAbstract.ToSetsAbstract<Key,Value>
public interface IMultiLookup<Key,Value>
A multi-map that associates sets / multisets / delta sets of values to each key.Implementors must provide semantic (not identity-based) hashCode() and equals() using the static helpers
hashCode(IMultiLookup)
andequals(IMultiLookup, Object)
here.- Since:
- 2.0
- No Implement:
- This interface is not intended to be implemented by clients.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
IMultiLookup.ChangeGranularity
How significant was the change? *
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description IMultiLookup.ChangeGranularity
addPair(Key key, Value value)
Adds key-value pair to the lookup structure, or fails if not possible.IMultiLookup.ChangeGranularity
addPairOrNop(Key key, Value value)
Adds key-value pair to the lookup structure.IMultiLookup.ChangeGranularity
addPairPositiveMultiplicity(Key key, Value value, int count)
Updates multiplicity of key-value pair by a positive amount.void
clear()
Empties out the lookup structure.int
countKeys()
java.lang.Iterable<Key>
distinctKeys()
java.util.stream.Stream<Key>
distinctKeysStream()
java.lang.Iterable<Value>
distinctValues()
Iterates once over each distinct value.java.util.stream.Stream<Value>
distinctValuesStream()
Iterates once over each distinct value.static <Key,Value>
booleanequals(IMultiLookup<Key,Value> self, java.lang.Object obj)
Provides semantic equality comparison.static <Key,Value>
inthashCode(IMultiLookup<Key,Value> memory)
Provides semantic hashCode() comparison.boolean
isEmpty()
Returns true if this collection is empty, false otherwise.IMemoryView<Value>
lookup(Key key)
Returns a (read-only) bucket of values associated with the given key.IMemoryView<Value>
lookupAndRemoveAll(Key key)
Returns a (read-only) bucket of values associated with the given key, while simultaneously removing them.boolean
lookupExists(Key key)
Returns true if there are any values associated with the given key.default IMemoryView<Value>
lookupOrEmpty(Key key)
Returns a (read-only) bucket of values associated with the given key.IMemoryView<Value>
lookupUnsafe(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key, which can be of any type.default IMemoryView<Value>
lookupUnsafeOrEmpty(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key.IMultiLookup.ChangeGranularity
removePair(Key key, Value value)
Removes key-value pair from the lookup structure, or fails if not possible.IMultiLookup.ChangeGranularity
removePairOrNop(Key key, Value value)
Removes key-value pair from the lookup structure.
-
-
-
Method Detail
-
isEmpty
boolean isEmpty()
Returns true if this collection is empty, false otherwise.- Since:
- 2.2
-
lookupExists
boolean lookupExists(Key key)
Returns true if there are any values associated with the given key.- Parameters:
key
- a key for which associated values are sought- Since:
- 2.3
-
lookup
IMemoryView<Value> lookup(Key key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key
- a key for which associated values are sought- Returns:
- null if key not found, a bucket of values otherwise
-
lookupOrEmpty
default IMemoryView<Value> lookupOrEmpty(Key key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key
- a key for which associated values are sought- Returns:
- a bucket of values, never null
-
lookupAndRemoveAll
IMemoryView<Value> lookupAndRemoveAll(Key key)
Returns a (read-only) bucket of values associated with the given key, while simultaneously removing them. Clients must not modify the returned bucket.- Parameters:
key
- a key for which associated values are sought- Returns:
- a bucket of values, never null
- Since:
- 2.3
-
lookupUnsafe
IMemoryView<Value> lookupUnsafe(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key, which can be of any type. Clients must not modify the returned bucket.- Parameters:
key
- a key for which associated values are sought (may or may not be of Key type)- Returns:
- null if key not found, a bucket of values otherwise
-
lookupUnsafeOrEmpty
default IMemoryView<Value> lookupUnsafeOrEmpty(java.lang.Object key)
Returns a (read-only) bucket of values associated with the given key. Clients must not modify the returned bucket.- Parameters:
key
- a key for which associated values are sought (may or may not be of Key type)- Returns:
- a bucket of values, never null
-
distinctKeys
java.lang.Iterable<Key> distinctKeys()
- Returns:
- the set of distinct keys that have values associated.
-
distinctKeysStream
java.util.stream.Stream<Key> distinctKeysStream()
- Returns:
- the set of distinct keys that have values associated.
- Since:
- 2.3
-
countKeys
int countKeys()
- Returns:
- the number of distinct keys that have values associated.
-
distinctValues
java.lang.Iterable<Value> distinctValues()
Iterates once over each distinct value.
-
distinctValuesStream
java.util.stream.Stream<Value> distinctValuesStream()
Iterates once over each distinct value.- Since:
- 2.3
-
addPair
IMultiLookup.ChangeGranularity addPair(Key key, Value value)
Adds key-value pair to the lookup structure, or fails if not possible.If the addition would cause duplicates but the bucket type does not allow it (
CollectionsFactory.MemoryType.SETS
), the operation throws anIllegalStateException
.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException
- if addition would cause duplication that is not permitted
-
addPairOrNop
IMultiLookup.ChangeGranularity addPairOrNop(Key key, Value value)
Adds key-value pair to the lookup structure.If the addition would cause duplicates but the bucket type does not allow it (
CollectionsFactory.MemoryType.SETS
), the operation is silently ignored andIMultiLookup.ChangeGranularity.DUPLICATE
is returned.- Returns:
- the granularity of the change, or
IMultiLookup.ChangeGranularity.DUPLICATE
if addition would result in a duplicate and therefore ignored - Since:
- 2.3
-
removePair
IMultiLookup.ChangeGranularity removePair(Key key, Value value)
Removes key-value pair from the lookup structure, or fails if not possible.When attempting to remove a key-value pair with zero multiplicity from a non-delta bucket type (
CollectionsFactory.MemoryType.SETS
orCollectionsFactory.MemoryType.MULTISETS
}), anIllegalStateException
is thrown.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException
- if removing non-existing element that is not permitted
-
removePairOrNop
IMultiLookup.ChangeGranularity removePairOrNop(Key key, Value value)
Removes key-value pair from the lookup structure.When attempting to remove a key-value pair with zero multiplicity from a non-delta bucket type (
CollectionsFactory.MemoryType.SETS
orCollectionsFactory.MemoryType.MULTISETS
}), the operation is silently ignored andIMultiLookup.ChangeGranularity.DUPLICATE
is returned.- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException
- if removing non-existing element that is not permitted- Since:
- 2.3
-
addPairPositiveMultiplicity
IMultiLookup.ChangeGranularity addPairPositiveMultiplicity(Key key, Value value, int count)
Updates multiplicity of key-value pair by a positive amount.PRE: count > 0
- Returns:
- the granularity of the change
- Throws:
java.lang.IllegalStateException
- if addition would cause duplication that is not permitted
-
clear
void clear()
Empties out the lookup structure.
-
equals
static <Key,Value> boolean equals(IMultiLookup<Key,Value> self, java.lang.Object obj)
Provides semantic equality comparison.
-
hashCode
static <Key,Value> int hashCode(IMultiLookup<Key,Value> memory)
Provides semantic hashCode() comparison.
-
-