Package org.eclipse.viatra.query.runtime.matchers.util

## Interface IMemory<T>

- All Superinterfaces:
    `Clearable`, `IMemoryView<T>`, `java.lang.Iterable<T>`
  All Known Subinterfaces:
    `IDeltaBag<T>`, `IMultiset<T>`, `ISetMemory<T>`, `MarkedMemory<Value>`, `MarkedMemory.MarkedDeltaBag<Value>`, `MarkedMemory.MarkedMultiset<Value>`, `MarkedMemory.MarkedSet<Value>`
  All Known Implementing Classes:
    `EclipseCollectionsBagMemory`, `EclipseCollectionsDeltaBag`, `EclipseCollectionsLongMultiset`, `EclipseCollectionsLongSetMemory`, `EclipseCollectionsMultiset`, `EclipseCollectionsSetMemory`

      public interface IMemory<T>
      extends IMemoryView<T>, Clearable

  A memory containing a positive or negative number of equal() copies for some values. During iterations, each distinct value is iterated only once.

  Refined by:

  - `IMultiset`, which always contains values with a nonnegative multiplicity.
  - `IDeltaBag`, which may contain values with negative multiplicity.
  - `ISetMemory`, which is just a set (allowed multiplicities: 0 and 1).
  Since:
    1.7
  No Implement:
    This interface is not intended to be implemented by clients.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `addOne​(T value)` | Adds one value occurrence to the memory.
    `boolean` | `addSigned​(T value, int count)` | Adds the given number of occurrences to the memory.
    `void` | `clear()` | Empties out the memory.
    `void` | `clearAllOf​(T value)` | Removes all occurrences of the given value from the memory.
    `boolean` | `removeOne​(T value)` | Removes one occurrence of the given value from the memory.
    `boolean` | `removeOneOrNop​(T value)` | Removes one occurrence of the given value from the memory, if possible.

    - ### Methods inherited from interface org.eclipse.viatra.query.runtime.matchers.util.IMemoryView

      `asMap, asStream, containsNonZero, containsNonZeroUnsafe, distinctValues, entriesWithMultiplicities, forEachEntryWithMultiplicities, getCount, getCountUnsafe, isEmpty, size, theContainedVersionOf, theContainedVersionOfUnsafe`

    - ### Methods inherited from interface java.lang.Iterable

      `forEach, iterator, spliterator`

- - ### Method Detail

    - #### addOne

          boolean addOne​(T value)

      Adds one value occurrence to the memory.
      Returns:
        true if the tuple was not present before in the memory, or (in case of `IDeltaBag`) is no longer present in the memory

    - #### addSigned

          boolean addSigned​(T value,
                            int count)

      Adds the given number of occurrences to the memory. The count value may or may not be negative.

      Precondition if `IMultiset`: at least the given amount of occurrences exist, if count is negative.

      Precondition if `ISetMemory`: count is +1 or -1, the latter is only allowed if the set contains the value.

      Parameters:
        `count` - the number of occurrences
      Returns:
        true if the tuple was not present before in the memory, or is no longer present in the memory
      Throws:
        `java.lang.IllegalStateException` - if `IMultiset` or `ISetMemory` and the number of occurrences in the memory would underflow to negative

    - #### removeOne

          boolean removeOne​(T value)

      Removes one occurrence of the given value from the memory.

      Precondition if `IMultiset` or `ISetMemory`: the value must have a positive amount of occurrences in the memory.

      Returns:
        true if this was the the last occurrence of the value, or (in case of `IDeltaBag`) is the first negative occurrence of the value
      Throws:
        `java.lang.IllegalStateException` - if `IMultiset` or `ISetMemory` and value had no occurrences in the memory

    - #### removeOneOrNop

          boolean removeOneOrNop​(T value)

      Removes one occurrence of the given value from the memory, if possible.

      Memory is unchanged and false is returned if `IMultiset` or `ISetMemory` and value had no occurrences in the memory

      Returns:
        true if this was the the last occurrence of the value, or (in case of `IDeltaBag`) is the first negative occurrence of the value
      Since:
        2.3

    - #### clearAllOf

          void clearAllOf​(T value)

      Removes all occurrences of the given value from the memory.

    - #### clear

          void clear()

      Empties out the memory.
      Specified by:
        `clear` in interface `Clearable`