Class 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 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 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 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, int[] selectedIndices)
      Creates a TupleMask instance that selects given positions.
      static TupleMask fromSelectedIndices​(int sourceArity, java.util.Collection<java.lang.Integer> 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()  
      <T> java.util.List<T> transform​(java.util.List<T> original)
      Generates an immutable, masked view of the original tuple.
      Tuple transform​(ITuple 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