< prev index next >

src/jdk.incubator.vector/share/classes/jdk/incubator/vector/VectorShuffle.java

Print this page
rev 54658 : refactored mask and shuffle creation methods, moved classes to top-level
rev 54659 : changed VectorSpecies to interface and moved stuff to AbstractSpecies
rev 54660 : Javadoc changes


 113 
 114     /**
 115      * Returns a shuffle where each lane element is the value of its
 116      * corresponding lane index.
 117      * <p>
 118      * This method behaves as if a shuffle is created from an identity
 119      * index mapping function as follows:
 120      * <pre>{@code
 121      *   return VectorShuffle.shuffle(i -> i);
 122      * }</pre>
 123      *
 124      * @param species shuffle species
 125      * @return a shuffle of lane indexes
 126      */
 127     @ForceInline
 128     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species) {
 129         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(AbstractShuffle.IDENTITY);
 130     }
 131 
 132     /**





































 133      * Returns a shuffle where each lane element is set to a given
 134      * {@code int} value logically AND'ed by the species length minus one.
 135      * <p>
 136      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 137      * the {@code int} value at index {@code N} logically AND'ed by
 138      * {@code species.length() - 1} is placed into the resulting shuffle at
 139      * lane index {@code N}.
 140      *
 141      * @param species shuffle species
 142      * @param ixs the given {@code int} values
 143      * @return a shuffle where each lane element is set to a given
 144      * {@code int} value
 145      * @throws IndexOutOfBoundsException if the number of int values is
 146      * {@code < species.length()}
 147      */
 148     @ForceInline
 149     public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... ixs) {
 150         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, 0);
 151     }
 152 
 153     /**
 154      * Loads a shuffle from an {@code int} array starting at an offset.
 155      * <p>
 156      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 157      * array element at index {@code i + N} logically AND'ed by
 158      * {@code species.length() - 1} is placed into the resulting shuffle at lane
 159      * index {@code N}.
 160      *
 161      * @param species shuffle species
 162      * @param ixs the {@code int} array
 163      * @param i the offset into the array
 164      * @return a shuffle loaded from the {@code int} array
 165      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 166      * {@code i > a.length - species.length()}
 167      */
 168     @ForceInline
 169     public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] ixs, int i) {
 170         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, i);
 171     }
 172 
 173     /**
 174      * Returns an {@code int} array containing the lane elements of this
 175      * shuffle.
 176      * <p>
 177      * This method behaves as if it {@link #intoArray(int[], int)} stores}
 178      * this shuffle into an allocated array and returns that array as
 179      * follows:
 180      * <pre>{@code
 181      *   int[] a = new int[this.length()];
 182      *   VectorShuffle.intoArray(a, 0);
 183      *   return a;
 184      * }</pre>
 185      *
 186      * @return an array containing the the lane elements of this vector
 187      */
 188     public abstract int[] toArray();
 189 
 190     /**
 191      * Stores this shuffle into an {@code int} array starting at offset.
 192      * <p>
 193      * For each shuffle lane, where {@code N} is the shuffle lane index,
 194      * the lane element at index {@code N} is stored into the array at index
 195      * {@code i + N}.
 196      *
 197      * @param a the array
 198      * @param i the offset into the array
 199      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 200      * {@code i > a.length - this.length()}
 201      */
 202     public abstract void intoArray(int[] a, int i);
 203 
 204     /**
 205      * Converts this shuffle into a vector, creating a vector from shuffle
 206      * lane elements (int values) cast to the vector element type.
 207      * <p>
 208      * This method behaves as if it returns the result of creating a
 209      * vector given an {@code int} array obtained from this shuffle's
 210      * lane elements, as follows:
 211      * <pre>{@code
 212      *   int[] sa = this.toArray();
 213      *   $type$[] va = new $type$[a.length];
 214      *   for (int i = 0; i < a.length; i++) {
 215      *       va[i] = ($type$) sa[i];
 216      *   }
 217      *   return IntVector.fromArray(va, 0);
 218      * }</pre>
 219      *
 220      * @return a vector representation of this shuffle
 221      */
 222     public abstract Vector<E> toVector();
 223 
 224     /**
 225      * Gets the {@code int} lane element at lane index {@code i}
 226      *
 227      * @param i the lane index
 228      * @return the {@code int} lane element at lane index {@code i}
 229      */
 230     public int getElement(int i) { return toArray()[i]; }
 231 
 232     /**
 233      * Rearranges the lane elements of this shuffle selecting lane indexes
 234      * controlled by another shuffle.
 235      * <p>
 236      * For each lane of the specified shuffle, at lane index {@code N} with lane
 237      * element {@code I}, the lane element at {@code I} from this shuffle is
 238      * selected and placed into the resulting shuffle at {@code N}.
 239      *
 240      * @param s the shuffle controlling lane index selection
 241      * @return the rearrangement of the lane elements of this shuffle
 242      */
 243     public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s);
 244 }


 113 
 114     /**
 115      * Returns a shuffle where each lane element is the value of its
 116      * corresponding lane index.
 117      * <p>
 118      * This method behaves as if a shuffle is created from an identity
 119      * index mapping function as follows:
 120      * <pre>{@code
 121      *   return VectorShuffle.shuffle(i -> i);
 122      * }</pre>
 123      *
 124      * @param species shuffle species
 125      * @return a shuffle of lane indexes
 126      */
 127     @ForceInline
 128     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species) {
 129         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(AbstractShuffle.IDENTITY);
 130     }
 131 
 132     /**
 133      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}.
 134      * <p>
 135      * This method behaves as if a shuffle is created from an identity
 136      * index mapping function as follows:
 137      * <pre>{@code
 138      *   return VectorShuffle.shuffle(i -> i + start);
 139      * }</pre>
 140      *
 141      * @param species shuffle species
 142      * @param start starting value of sequence
 143      * @return a shuffle of lane indexes
 144      */
 145     @ForceInline
 146     public static <E> VectorShuffle<E> shuffleIota(VectorSpecies<E> species, int start) {
 147         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(i -> i + start);
 148     }
 149 
 150     /**
 151      * Returns a shuffle with lane elements set to sequential {@code int} values starting from {@code start}
 152      * and looping around species length.
 153      * <p>
 154      * This method behaves as if a shuffle is created from an identity
 155      * index mapping function as follows:
 156      * <pre>{@code
 157      *   return VectorShuffle.shuffle(i -> (i + start) & (species.length() - 1));
 158      * }</pre>
 159      *
 160      * @param species shuffle species
 161      * @param start starting value of sequence
 162      * @return a shuffle of lane indexes
 163      */
 164     @ForceInline
 165     public static <E> VectorShuffle<E> shuffleOffset(VectorSpecies<E> species, int start) {
 166         return ((AbstractSpecies<E>) species).shuffleFromOpFactory.apply(i -> (i + start) & (species.length() - 1));
 167     }
 168 
 169     /**
 170      * Returns a shuffle where each lane element is set to a given
 171      * {@code int} value logically AND'ed by the species length minus one.
 172      * <p>
 173      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 174      * the {@code int} value at index {@code N} logically AND'ed by
 175      * {@code species.length() - 1} is placed into the resulting shuffle at
 176      * lane index {@code N}.
 177      *
 178      * @param species shuffle species
 179      * @param ixs the given {@code int} values
 180      * @return a shuffle where each lane element is set to a given
 181      * {@code int} value
 182      * @throws IndexOutOfBoundsException if the number of int values is
 183      * {@code < species.length()}
 184      */
 185     @ForceInline
 186     public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... ixs) {
 187         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, 0);
 188     }
 189 
 190     /**
 191      * Loads a shuffle from an {@code int} array starting at an offset.
 192      * <p>
 193      * For each shuffle lane, where {@code N} is the shuffle lane index, the
 194      * array element at index {@code i + N} logically AND'ed by
 195      * {@code species.length() - 1} is placed into the resulting shuffle at lane
 196      * index {@code N}.
 197      *
 198      * @param species shuffle species
 199      * @param ixs the {@code int} array
 200      * @param offset the offset into the array
 201      * @return a shuffle loaded from the {@code int} array
 202      * @throws IndexOutOfBoundsException if {@code offset < 0}, or
 203      * {@code offset > a.length - species.length()}
 204      */
 205     @ForceInline
 206     public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] ixs, int offset) {
 207         return ((AbstractSpecies<E>) species).shuffleFromArrayFactory.apply(ixs, offset);
 208     }
 209 
 210     /**
 211      * Returns an {@code int} array containing the lane elements of this
 212      * shuffle.
 213      * <p>
 214      * This method behaves as if it {@link #intoArray(int[], int)} stores}
 215      * this shuffle into an allocated array and returns that array as
 216      * follows:
 217      * <pre>{@code
 218      *   int[] a = new int[this.length()];
 219      *   VectorShuffle.intoArray(a, 0);
 220      *   return a;
 221      * }</pre>
 222      *
 223      * @return an array containing the the lane elements of this vector
 224      */
 225     public abstract int[] toArray();
 226 
 227     /**
 228      * Stores this shuffle into an {@code int} array starting at offset.
 229      * <p>
 230      * For each shuffle lane, where {@code N} is the shuffle lane index,
 231      * the lane element at index {@code N} is stored into the array at index
 232      * {@code i + N}.
 233      *
 234      * @param a the array
 235      * @param offset the offset into the array
 236      * @throws IndexOutOfBoundsException if {@code i < 0}, or
 237      * {@code offset > a.length - this.length()}
 238      */
 239     public abstract void intoArray(int[] a, int offset);
 240 
 241     /**
 242      * Converts this shuffle into a vector, creating a vector from shuffle
 243      * lane elements (int values) cast to the vector element type.
 244      * <p>
 245      * This method behaves as if it returns the result of creating a
 246      * vector given an {@code int} array obtained from this shuffle's
 247      * lane elements, as follows:
 248      * <pre>{@code
 249      *   int[] sa = this.toArray();
 250      *   $type$[] va = new $type$[a.length];
 251      *   for (int i = 0; i < a.length; i++) {
 252      *       va[i] = ($type$) sa[i];
 253      *   }
 254      *   return IntVector.fromArray(va, 0);
 255      * }</pre>
 256      *
 257      * @return a vector representation of this shuffle
 258      */
 259     public abstract Vector<E> toVector();
 260 
 261     /**
 262      * Gets the {@code int} lane element at lane index {@code i}
 263      *
 264      * @param i the lane index
 265      * @return the {@code int} lane element at lane index {@code i}
 266      */
 267     public int lane(int i) { return toArray()[i]; }
 268 
 269     /**
 270      * Rearranges the lane elements of this shuffle selecting lane indexes
 271      * controlled by another shuffle.
 272      * <p>
 273      * For each lane of the specified shuffle, at lane index {@code N} with lane
 274      * element {@code I}, the lane element at {@code I} from this shuffle is
 275      * selected and placed into the resulting shuffle at {@code N}.
 276      *
 277      * @param s the shuffle controlling lane index selection
 278      * @return the rearrangement of the lane elements of this shuffle
 279      */
 280     public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s);
 281 }
< prev index next >