org.eclipse.viatra.query.runtime.matchers.tuple

## Class TupleMask

- java.lang.Object
- - org.eclipse.viatra.query.runtime.matchers.tuple.TupleMask

- Direct Known Subclasses:
    TupleMask0, TupleMaskIdentity

      public class TupleMask
      extends java.lang.Object

  Specifies select indices of a tuple. If viewed through this mask (see `transform(ITuple)`), the signature of the pattern will consist of its individual substitutions at the given positions, in the exact same order as they appear in indices[].

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `int[]` | `indices` indices[i] specifies the index of the substitution in the original tuple that occupies the i-th place in the masked signature.
    `int` | `sourceWidth` the size of the tuple this mask is applied to

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TupleMask(int[] indices, int sourceWidth, int[] indicesSorted, java.lang.Boolean isNonrepeating)` Creates a TupleMask instance with the given indices array

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static TupleMask` | `append(TupleMask left, TupleMask right)` Creates a TupleMask instance that selects whatever is selected by left, and appends whatever is selected by right.
    `Tuple` | `combine(Tuple unmasked, Tuple masked, boolean useInheritance, boolean asComplementer)` Combines two substitutions.
    `protected static int[]` | `constructLinearSequence(int size)` An array containing the first `size` nonnegative integers in order
    `static TupleMask` | `displace(int from, int to, int sourceWidth)` Creates a TupleMask instance that moves an element from one index to other, shifting the others if neccessary.
    `static TupleMask` | `empty(int sourceWidth)` Creates a TupleMask instance of the given size that does not emit output.
    `boolean` | `equals(java.lang.Object obj)`
    `static TupleMask` | `fromKeepIndicators(boolean[] keep)` Creates a TupleMask instance that selects positions where keep is true
    `static TupleMask` | `fromNonNullIndices(ITuple tuple)` Creates a TupleMask instance that selects non-null positions of a given tuple
    `static TupleMask` | `fromSelectedIndices(int sourceArity, java.util.Collection<java.lang.Integer> selectedIndices)` Creates a TupleMask instance that selects given positions.
    `static TupleMask` | `fromSelectedIndices(int sourceArity, int[] selectedIndices)` Creates a TupleMask instance that selects given positions.
    `protected static TupleMask` | `fromSelectedIndicesInternal(int[] selectedIndices, int sourceArity, int[] indicesSorted, java.lang.Boolean isNonrepeating)` Creates a TupleMask instance that selects given positions.
    `protected static TupleMask` | `fromSelectedMonotonicIndicesInternal(int[] selectedIndices, int sourceArity)` Creates a TupleMask instance that selects given positions in monotonically increasing order.
    `java.util.OptionalInt` | `getFirstOmittedIndex()` Returns the first index of the source that is not selected by the mask, or empty if all indices are selected.
    `java.util.List<java.lang.Integer>` | `getIndicesAsList()`
    `int` | `getSize()` Returns the size of the masked tuples described by this mask
    `int` | `getSourceWidth()` Returns the size of the original tuples handled by this mask
    `java.lang.Object` | `getValue(ITuple original, int index)` Returns a selected masked value from the selected tuple.
    `int` | `hashCode()`
    `static TupleMask` | `identity(int size)` Creates a TupleMask instance of the given size that maps every single element intact
    `static int[]` | `integersToIntArray(java.util.Collection<java.lang.Integer> selectedIndices)`
    `boolean` | `isIdentity()`
    `boolean` | `isNonrepeating()`
    `Tuple` | `keepSelectedIndices(ITuple original)` Returns a tuple `result`, same arity as the original tuple, that satisfies `this.transform(result).equals(this.transform(tuple))`.
    `static TupleMask` | `linear(int size, int sourceWidth)` Creates a TupleMask instance of the given size that maps the first 'size' elements intact
    `static TupleMask` | `omit(int omission, int sourceWidth)` Creates a TupleMask instance that maps the tuple intact save for a single element at the specified index which is omitted
    `Tuple` | `revertFrom(ITuple masked)` Returns a tuple `result` that satisfies `this.transform(result).equals(masked)`.
    `static TupleMask` | `selectSingle(int selected, int sourceWidth)` Creates a TupleMask instance that selects a single element of the tuple.
    `void` | `set(IModifiableTuple tuple, int index, java.lang.Object value)` Sets the selected value in the original tuple based on the mask definition
    `java.lang.String` | `toString()`
    `Tuple` | `transform(ITuple original)` Generates an immutable, masked view of the original tuple.
    `<T> java.util.List<T>` | `transform(java.util.List<T> original)` Generates an immutable, masked view of the original tuple.
    `TupleMask` | `transform(TupleMask mask)` Transforms a given mask directly, instead of transforming tuples that were transformed by the other mask.
    `<T> java.util.Set<T>` | `transformUnique(java.util.List<T> original)` Transforms the given list by applying the mask and putting all results into a set; keeping only a single element in case of the mapping result in duplicate values.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### indices

          public final int[] indices

      indices[i] specifies the index of the substitution in the original tuple that occupies the i-th place in the masked signature.

    - #### sourceWidth

          public int sourceWidth

      the size of the tuple this mask is applied to

  - ### Constructor Detail

    - #### TupleMask

          protected TupleMask(int[] indices,
                              int sourceWidth,
                              int[] indicesSorted,
                              java.lang.Boolean isNonrepeating)

      Creates a TupleMask instance with the given indices array

      indicesSorted and isNonrepeating may be OPTIONALLY given if known.

      Since:
        2.0

  - ### Method Detail

    - #### fromSelectedIndicesInternal

          protected static TupleMask fromSelectedIndicesInternal(int[] selectedIndices,
                                                                 int sourceArity,
                                                                 int[] indicesSorted,
                                                                 java.lang.Boolean isNonrepeating)

      Creates a TupleMask instance that selects given positions. The mask takes ownership of the array selectedIndices, the client must not modify it afterwards.

      indicesSorted and isNonrepeating may be OPTIONALLY given if known.

      Since:
        2.0

    - #### fromSelectedMonotonicIndicesInternal

          protected static TupleMask fromSelectedMonotonicIndicesInternal(int[] selectedIndices,
                                                                          int sourceArity)

      Creates a TupleMask instance that selects given positions in monotonically increasing order. The mask takes ownership of the array selectedIndices, the client must not modify it afterwards.
      Since:
        2.0

    - #### linear

          public static TupleMask linear(int size,
                                         int sourceWidth)

      Creates a TupleMask instance of the given size that maps the first 'size' elements intact

    - #### constructLinearSequence

          protected static int[] constructLinearSequence(int size)

      An array containing the first `size` nonnegative integers in order
      Since:
        2.0

    - #### identity

          public static TupleMask identity(int size)

      Creates a TupleMask instance of the given size that maps every single element intact

    - #### empty

          public static TupleMask empty(int sourceWidth)

      Creates a TupleMask instance of the given size that does not emit output.

    - #### omit

          public static TupleMask omit(int omission,
                                       int sourceWidth)

      Creates a TupleMask instance that maps the tuple intact save for a single element at the specified index which is omitted

    - #### fromKeepIndicators

          public static TupleMask fromKeepIndicators(boolean[] keep)

      Creates a TupleMask instance that selects positions where keep is true
      Since:
        1.7

    - #### fromSelectedIndices

          public static TupleMask fromSelectedIndices(int sourceArity,
                                                      java.util.Collection<java.lang.Integer> selectedIndices)

      Creates a TupleMask instance that selects given positions.
      Since:
        1.7

    - #### fromSelectedIndices

          public static TupleMask fromSelectedIndices(int sourceArity,
                                                      int[] selectedIndices)

      Creates a TupleMask instance that selects given positions.
      Since:
        1.7

    - #### fromNonNullIndices

          public static TupleMask fromNonNullIndices(ITuple tuple)

      Creates a TupleMask instance that selects non-null positions of a given tuple
      Since:
        1.7

    - #### integersToIntArray

          public static int[] integersToIntArray(java.util.Collection<java.lang.Integer> selectedIndices)

      Since:
        1.7

    - #### displace

          public static TupleMask displace(int from,
                                           int to,
                                           int sourceWidth)

      Creates a TupleMask instance that moves an element from one index to other, shifting the others if neccessary.

    - #### selectSingle

          public static TupleMask selectSingle(int selected,
                                               int sourceWidth)

      Creates a TupleMask instance that selects a single element of the tuple.

    - #### append

          public static TupleMask append(TupleMask left,
                                         TupleMask right)

      Creates a TupleMask instance that selects whatever is selected by left, and appends whatever is selected by right. PRE: left and right have the same sourcewidth

    - #### getFirstOmittedIndex

          public java.util.OptionalInt getFirstOmittedIndex()

      Returns the first index of the source that is not selected by the mask, or empty if all indices are selected.

      PRE: mask indices are all different

      Since:
        2.0

    - #### getValue

          public java.lang.Object getValue(ITuple original,
                                           int index)

      Returns a selected masked value from the selected tuple.
      Since:
        1.7

    - #### set

          public void set(IModifiableTuple tuple,
                          int index,
                          java.lang.Object value)

      Sets the selected value in the original tuple based on the mask definition
      Since:
        1.7

    - #### transform

          public Tuple transform(ITuple original)

      Generates an immutable, masked view of the original tuple.

      The new tuple will have arity `getSize()`, and will consist of the elements of the original tuple, at positions indicated by this mask.

      Since:
        1.7

    - #### isNonrepeating

          public boolean isNonrepeating()

      Returns:
        true iff no two selected indices are the same
      Since:
        2.0

    - #### revertFrom

          public Tuple revertFrom(ITuple masked)

      Returns a tuple `result` that satisfies `this.transform(result).equals(masked)`. Positions of the result tuple that are not determined this way will be filled with null.
      Since:
        1.7

    - #### keepSelectedIndices

          public Tuple keepSelectedIndices(ITuple original)

      Returns a tuple `result`, same arity as the original tuple, that satisfies `this.transform(result).equals(this.transform(tuple))`. Positions of the result tuple that are not determined this way will be filled with null.

      In other words, a copy of the original tuple is returned, with null substituted at each position that is not selected by this mask.

      Since:
        2.1

    - #### transform

          public <T> java.util.List<T> transform(java.util.List<T> original)

      Generates an immutable, masked view of the original tuple.

      The list will have arity `getSize()`, and will consist of the elements of the original tuple, at positions indicated by this mask.

    - #### transform

          public TupleMask transform(TupleMask mask)

      Transforms a given mask directly, instead of transforming tuples that were transformed by the other mask.
      Returns:
        a mask that cascades the effects this mask after the mask provided as parameter.

    - #### combine

          public Tuple combine(Tuple unmasked,
                               Tuple masked,
                               boolean useInheritance,
                               boolean asComplementer)

      Combines two substitutions. The new pattern will contain all substitutions of masked and unmasked, assuming that the elements of masked indicated by this mask are already matched against unmasked. POST: the result will start with an exact copy of unmasked
      Parameters:
        `unmasked` - primary pattern substitution that is left intact.
        `masked` - secondary pattern substitution that is transformed to the end of the result.
        `useInheritance` - whether to use inheritance or copy umasked into result instead.
        `asComplementer` - whether this mask maps from the masked Tuple to the tail of the result or to the unmasked one.
      Returns:
        new pattern that is a combination of unmasked and masked.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### equals

          public boolean equals(java.lang.Object obj)

      Overrides:
        `equals` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getSize

          public int getSize()

      Returns the size of the masked tuples described by this mask
      Since:
        1.7

    - #### getSourceWidth

          public int getSourceWidth()

      Returns the size of the original tuples handled by this mask
      Since:
        1.7

    - #### isIdentity

          public boolean isIdentity()

      Returns:
        true iff this mask is a no-op
      Since:
        2.0

    - #### transformUnique

          public <T> java.util.Set<T> transformUnique(java.util.List<T> original)

      Transforms the given list by applying the mask and putting all results into a set; keeping only a single element in case of the mapping result in duplicate values.
      Since:
        1.7

    - #### getIndicesAsList

          public java.util.List<java.lang.Integer> getIndicesAsList()

      Returns:
        the list of selected indices
      Since:
        2.1