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 and 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, equals, forEachEntryWithMultiplicities, fromMap, getCount, getCountUnsafe, hashCode, 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`