Package tools.refinery.interpreter.matchers.util

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) and equals(IMultiLookup, Object) here.

Since:
2.0

  • Method Details

    • 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(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(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

      Iterable<Key> distinctKeys()
      Returns:
      the set of distinct keys that have values associated.

    • distinctKeysStream

      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

      Iterable<Value> distinctValues()
      Iterates once over each distinct value.

    • distinctValuesStream

      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 an IllegalStateException.

      Returns:
      the granularity of the change
      Throws:
      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 and IMultiLookup.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 or CollectionsFactory.MemoryType.MULTISETS}), an IllegalStateException is thrown.

      Returns:
      the granularity of the change
      Throws:
      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 or CollectionsFactory.MemoryType.MULTISETS}), the operation is silently ignored and IMultiLookup.ChangeGranularity.DUPLICATE is returned.

      Returns:
      the granularity of the change
      Throws:
      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:
      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, Object obj)
      Provides semantic equality comparison.

    • hashCode

      static <Key, Value> int hashCode(IMultiLookup<Key,Value> memory)
      Provides semantic hashCode() comparison.