Package 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 | 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> 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.