org.eclipse.viatra.query.runtime.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
  No Implement:
    This interface is not intended to be implemented by clients.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and 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 and 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> boolean` | `equals(IMultiLookup<Key,Value> self, java.lang.Object obj)` Provides semantic equality comparison.
    `static <Key,Value> int` | `hashCode(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 an `IllegalStateException`.

      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 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:
        `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` or `CollectionsFactory.MemoryType.MULTISETS`}), the operation is silently ignored and `IMultiLookup.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.