Module jdk.incubator.vector
Package jdk.incubator.vector

Class Shuffle<E>

  • Type Parameters:
    E - the boxed element type of this mask
    public abstract class Shuffle<E>
extends Object
    A Shuffle represents an ordered immutable sequence of int values. A Shuffle can be used with a shuffle accepting vector operation to control the rearrangement of lane elements of input vectors

    The number of values in the sequence is referred to as the Shuffle length. The length also corresponds to the number of Shuffle lanes. The lane element at lane index N (from 0, inclusive, to length, exclusive) corresponds to the N + 1'th value in the sequence. A Shuffle and Vector of the same element type and shape have the same number of lanes.

    A Shuffle describes how a lane element of a vector may cross lanes from its lane index, i say, to another lane index whose value is the Shuffle's lane element at lane index i. Shuffle lane elements will be in the range of 0 (inclusive) to the shuffle length (exclusive), and therefore cannot induce out of bounds errors when used with vectors operations and vectors of the same length.

    • Method Summary

      Modifier and Type Method Description
      abstract <F> Shuffle<F> cast​(Species<F> species)
      Converts this shuffle to a shuffle of the given species of element type F.
      static <E> Shuffle<E> fromArray​(Species<E> species, int[] ixs, int i)
      Loads a shuffle from an int array starting at an offset.
      static <E> Shuffle<E> fromValues​(Species<E> species, int... ixs)
      Returns a shuffle where each lane element is set to a given int value logically AND'ed by the species length minus one.
      int getElement​(int i)
      Gets the int lane element at lane index i
      abstract void intoArray​(int[] a, int i)
      Stores this shuffle into an int array starting at offset.
      int length()
      Returns the number of shuffle lanes (the length).
      abstract Shuffle<E> rearrange​(Shuffle<E> s)
      Rearranges the lane elements of this shuffle selecting lane indexes controlled by another shuffle.
      static <E> Shuffle<E> shuffle​(Species<E> species, IntUnaryOperator f)
      Returns a shuffle of mapped indexes where each lane element is the result of applying a mapping function to the corresponding lane index.
      static <E> Shuffle<E> shuffleIota​(Species<E> species)
      Returns a shuffle where each lane element is the value of its corresponding lane index.
      abstract Species<E> species()
      Returns the species of this shuffle.
      abstract int[] toArray()
      Returns an int array containing the lane elements of this shuffle.
      abstract Vector<E> toVector()
      Converts this shuffle into a vector, creating a vector from shuffle lane elements (int values) cast to the vector element type.

    • Method Detail

      • species

        public abstract Species<E> species()
        Returns the species of this shuffle.
        Returns:
        the species of this shuffle

      • length

        public int length()
        Returns the number of shuffle lanes (the length).
        Returns:
        the number of shuffle lanes

      • cast

        public abstract <F> Shuffle<F> cast​(Species<F> species)
        Converts this shuffle to a shuffle of the given species of element type F.

        For each shuffle lane, where N is the lane index, the shuffle element at index N is placed, unmodified, into the resulting shuffle at index N.

        Type Parameters:
        F - the boxed element type of the species
        Parameters:
        species - species of desired shuffle
        Returns:
        a shuffle converted by shape and element type
        Throws:
        IllegalArgumentException - if this shuffle length and the species length differ

      • shuffle

        public static <E> Shuffle<E> shuffle​(Species<E> species,
                                     IntUnaryOperator f)
        Returns a shuffle of mapped indexes where each lane element is the result of applying a mapping function to the corresponding lane index.

        Care should be taken to ensure Shuffle values produced from this method are consumed as constants to ensure optimal generation of code. For example, values held in static final fields or values held in loop constant local variables.

        This method behaves as if a shuffle is created from an array of mapped indexes as follows: 

        
   int[] a = new int[species.length()];
   for (int i = 0; i < a.length; i++) {
       a[i] = f.applyAsInt(i);
   }
   return this.shuffleFromValues(a);
        Parameters:
        species - shuffle species
        f - the lane index mapping function
        Returns:
        a shuffle of mapped indexes

      • shuffleIota

        public static <E> Shuffle<E> shuffleIota​(Species<E> species)
        Returns a shuffle where each lane element is the value of its corresponding lane index.

        This method behaves as if a shuffle is created from an identity index mapping function as follows: 

        
   return this.shuffle(i -> i);
        Parameters:
        species - shuffle species
        Returns:
        a shuffle of lane indexes

      • fromValues

        public static <E> Shuffle<E> fromValues​(Species<E> species,
                                        int... ixs)
        Returns a shuffle where each lane element is set to a given int value logically AND'ed by the species length minus one.

        For each shuffle lane, where N is the shuffle lane index, the the int value at index N logically AND'ed by species.length() - 1 is placed into the resulting shuffle at lane index N.

        Parameters:
        species - shuffle species
        ixs - the given int values
        Returns:
        a shuffle where each lane element is set to a given int value
        Throws:
        IndexOutOfBoundsException - if the number of int values is < species.length()

      • fromArray

        public static <E> Shuffle<E> fromArray​(Species<E> species,
                                       int[] ixs,
                                       int i)
        Loads a shuffle from an int array starting at an offset.

        For each shuffle lane, where N is the shuffle lane index, the array element at index i + N logically AND'ed by species.length() - 1 is placed into the resulting shuffle at lane index N.

        Parameters:
        species - shuffle species
        ixs - the int array
        i - the offset into the array
        Returns:
        a shuffle loaded from the int array
        Throws:
        IndexOutOfBoundsException - if i < 0, or i > a.length - species.length()

      • toArray

        public abstract int[] toArray()
        Returns an int array containing the lane elements of this shuffle.

        This method behaves as if it intoArray(int[], int) stores} this shuffle into an allocated array and returns that array as follows: 

        
   int[] a = new int[this.length()];
   this.intoArray(a, 0);
   return a;
        Returns:
        an array containing the the lane elements of this vector

      • intoArray

        public abstract void intoArray​(int[] a,
                               int i)
        Stores this shuffle into an int array starting at offset.

        For each shuffle lane, where N is the shuffle lane index, the lane element at index N is stored into the array at index i + N.

        Parameters:
        a - the array
        i - the offset into the array
        Throws:
        IndexOutOfBoundsException - if i < 0, or i > a.length - this.length()

      • toVector

        public abstract Vector<E> toVector()
        Converts this shuffle into a vector, creating a vector from shuffle lane elements (int values) cast to the vector element type.

        This method behaves as if it returns the result of creating a vector given an int array obtained from this shuffle's lane elements, as follows: 

        
   int[] sa = this.toArray();
   $type$[] va = new $type$[a.length];
   for (int i = 0; i < a.length; i++) {
       va[i] = ($type$) sa[i];
   }
   return this.species().fromArray(va, 0);
        Returns:
        a vector representation of this shuffle

      • getElement

        public int getElement​(int i)
        Gets the int lane element at lane index i
        Parameters:
        i - the lane index
        Returns:
        the int lane element at lane index i

      • rearrange

        public abstract Shuffle<E> rearrange​(Shuffle<E> s)
        Rearranges the lane elements of this shuffle selecting lane indexes controlled by another shuffle.

        For each lane of the shuffle, at lane index N with lane element I, the lane element at I from this shuffle is selected and placed into the resulting shuffle at N.

        Parameters:
        s - the shuffle controlling lane index selection
        Returns:
        the rearrangement of the lane elements of this shuffle