137 /**
138 * Returns the number of lanes processed by this shuffle.
139 * This is the same as the {@code VLENGTH} of any vector
140 * it operates on.
141 *
142 * @return the number of shuffle lanes
143 */
144 @ForceInline
145 public final int length() {
146 AbstractSpecies<E> vspecies = (AbstractSpecies<E>) vectorSpecies();
147 return vspecies.laneCount();
148 }
149
150 /**
151 * Converts this shuffle to a shuffle of the given species of
152 * element type {@code F}.
153 *
154 * The various lane source indexes are unmodified, except that any
155 * index that fails to validate against a changed {@code VLENGTH}
156 * is partially wrapped to an exceptional index, whether it was
157 * originally normal or exception.
158 *
159 * @param species the species of desired shuffle
160 * @param <F> the boxed element type of the species
161 * @return a shuffle converted by shape and element type
162 * @throws IllegalArgumentException if this shuffle length and the
163 * species length differ
164 */
165 public abstract <F> VectorShuffle<F> cast(VectorSpecies<F> species);
166
167 /**
168 * Checks that this shuffle has the given species,
169 * and returns this shuffle unchanged.
170 * The effect is similar to this pseudocode:
171 * {@code species == vectorSpecies()
172 * ? this
173 * : throw new ClassCastException()}.
174 *
175 * @param species the required species
176 * @param <F> the boxed element type of the required species
177 * @return the same shuffle
246 * Find all lanes containing valid indexes (non-negative values)
247 * and return a mask where exactly those lanes are set.
248 *
249 * @return a mask of lanes containing valid source indexes
250 * @see #checkIndexes()
251 */
252 public abstract VectorMask<E> laneIsValid();
253
254 /**
255 * Loads a shuffle for a given species from
256 * a series of source indexes.
257 *
258 * <p> For each shuffle lane, where {@code N} is the shuffle lane
259 * index, the {@code N}th index value is validated
260 * against the species {@code VLENGTH}, and (if invalid)
261 * is partially wrapped to an exceptional index in the
262 * range {@code [-VLENGTH..-1]}.
263 *
264 * @param species shuffle species
265 * @param sourceIndexes the source indexes which the shuffle will draw from
266 * @param offset the offset into the array
267 * @return a shuffle where each lane's source index is set to the given
268 * {@code int} value, partially wrapped if exceptional
269 * @throws IndexOutOfBoundsException if {@code offset < 0}, or
270 * {@code offset > sourceIndexes.length - VLENGTH}
271 * @see VectorSpecies#shuffleFromValues(int...)
272 */
273 @ForceInline
274 public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species,
275 int... sourceIndexes) {
276 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
277 VectorIntrinsics.requireLength(sourceIndexes.length, vsp.laneCount());
278 return vsp.shuffleFromArray(sourceIndexes, 0);
279 }
280
281 /**
282 * Loads a shuffle for a given species from
283 * an {@code int} array starting at an offset.
284 *
285 * <p> For each shuffle lane, where {@code N} is the shuffle lane
286 * index, the array element at index {@code i + N} is validated
287 * against the species {@code VLENGTH}, and (if invalid)
288 * is partially wrapped to an exceptional index in the
289 * range {@code [-VLENGTH..-1]}.
290 *
291 * @param species shuffle species
292 * @param sourceIndexes the source indexes which the shuffle will draw from
293 * @param offset the offset into the array
294 * @return a shuffle where each lane's source index is set to the given
295 * {@code int} value, partially wrapped if exceptional
296 * @throws IndexOutOfBoundsException if {@code offset < 0}, or
297 * {@code offset > sourceIndexes.length - VLENGTH}
298 * @see VectorSpecies#shuffleFromArray(int[], int)
299 */
300 @ForceInline
301 public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] sourceIndexes, int offset) {
302 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
303 return vsp.shuffleFromArray(sourceIndexes, offset);
304 }
305
306 /**
307 * Loads a shuffle for a given species from
308 * the successive values of an operator applied to
309 * the range {@code [0..VLENGTH-1]}.
310 *
311 * <p> For each shuffle lane, where {@code N} is the shuffle lane
312 * index, the {@code N}th index value is validated
313 * against the species {@code VLENGTH}, and (if invalid)
314 * is partially wrapped to an exceptional index in the
315 * range {@code [-VLENGTH..-1]}.
316 *
317 * <p> Care should be taken to ensure {@code VectorShuffle} values
318 * produced from this method are consumed as constants to ensure
319 * optimal generation of code. For example, shuffle values can be
320 * held in {@code static final} fields or loop-invariant local variables.
321 *
322 * <p> This method behaves as if a shuffle is created from an array of
323 * mapped indexes as follows:
324 * <pre>{@code
325 * int[] a = new int[species.length()];
326 * for (int i = 0; i < a.length; i++) {
327 * a[i] = f.applyAsInt(i);
328 * }
329 * return VectorShuffle.fromArray(a, 0);
330 * }</pre>
331 *
332 * @param species shuffle species
333 * @param f the lane index mapping function
334 * @return a shuffle of mapped indexes
335 * @see VectorSpecies#shuffleFromOp(IntUnaryOperator)
336 */
337 @ForceInline
338 public static <E> VectorShuffle<E> fromOp(VectorSpecies<E> species, IntUnaryOperator fn) {
339 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
340 return vsp.shuffleFromOp(fn);
341 }
342
343 /**
344 * Loads a shuffle using source indexes set to sequential
345 * values starting from {@code start} and stepping
346 * by the given {@code step}.
347 * <p>
348 * This method returns the value of the expression
349 * {@code VectorShuffle.fromOp(species, i -> start + i * step)}.
350 *
351 * @param species shuffle species
352 * @param start the starting value of the source index sequence
353 * @param step the difference between adjacent source indexes
|
137 /**
138 * Returns the number of lanes processed by this shuffle.
139 * This is the same as the {@code VLENGTH} of any vector
140 * it operates on.
141 *
142 * @return the number of shuffle lanes
143 */
144 @ForceInline
145 public final int length() {
146 AbstractSpecies<E> vspecies = (AbstractSpecies<E>) vectorSpecies();
147 return vspecies.laneCount();
148 }
149
150 /**
151 * Converts this shuffle to a shuffle of the given species of
152 * element type {@code F}.
153 *
154 * The various lane source indexes are unmodified, except that any
155 * index that fails to validate against a changed {@code VLENGTH}
156 * is partially wrapped to an exceptional index, whether it was
157 * originally normal or exceptional.
158 *
159 * @param species the species of desired shuffle
160 * @param <F> the boxed element type of the species
161 * @return a shuffle converted by shape and element type
162 * @throws IllegalArgumentException if this shuffle length and the
163 * species length differ
164 */
165 public abstract <F> VectorShuffle<F> cast(VectorSpecies<F> species);
166
167 /**
168 * Checks that this shuffle has the given species,
169 * and returns this shuffle unchanged.
170 * The effect is similar to this pseudocode:
171 * {@code species == vectorSpecies()
172 * ? this
173 * : throw new ClassCastException()}.
174 *
175 * @param species the required species
176 * @param <F> the boxed element type of the required species
177 * @return the same shuffle
246 * Find all lanes containing valid indexes (non-negative values)
247 * and return a mask where exactly those lanes are set.
248 *
249 * @return a mask of lanes containing valid source indexes
250 * @see #checkIndexes()
251 */
252 public abstract VectorMask<E> laneIsValid();
253
254 /**
255 * Loads a shuffle for a given species from
256 * a series of source indexes.
257 *
258 * <p> For each shuffle lane, where {@code N} is the shuffle lane
259 * index, the {@code N}th index value is validated
260 * against the species {@code VLENGTH}, and (if invalid)
261 * is partially wrapped to an exceptional index in the
262 * range {@code [-VLENGTH..-1]}.
263 *
264 * @param species shuffle species
265 * @param sourceIndexes the source indexes which the shuffle will draw from
266 * @return a shuffle where each lane's source index is set to the given
267 * {@code int} value, partially wrapped if exceptional
268 * @throws IndexOutOfBoundsException if {@code sourceIndexes.length != VLENGTH}
269 * @see VectorSpecies#shuffleFromValues(int...)
270 */
271 @ForceInline
272 public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species,
273 int... sourceIndexes) {
274 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
275 VectorIntrinsics.requireLength(sourceIndexes.length, vsp.laneCount());
276 return vsp.shuffleFromArray(sourceIndexes, 0);
277 }
278
279 /**
280 * Loads a shuffle for a given species from
281 * an {@code int} array starting at an offset.
282 *
283 * <p> For each shuffle lane, where {@code N} is the shuffle lane
284 * index, the array element at index {@code offset + N} is validated
285 * against the species {@code VLENGTH}, and (if invalid)
286 * is partially wrapped to an exceptional index in the
287 * range {@code [-VLENGTH..-1]}.
288 *
289 * @param species shuffle species
290 * @param sourceIndexes the source indexes which the shuffle will draw from
291 * @param offset the offset into the array
292 * @return a shuffle where each lane's source index is set to the given
293 * {@code int} value, partially wrapped if exceptional
294 * @throws IndexOutOfBoundsException if {@code offset < 0}, or
295 * {@code offset > sourceIndexes.length - VLENGTH}
296 * @see VectorSpecies#shuffleFromArray(int[], int)
297 */
298 @ForceInline
299 public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] sourceIndexes, int offset) {
300 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
301 return vsp.shuffleFromArray(sourceIndexes, offset);
302 }
303
304 /**
305 * Loads a shuffle for a given species from
306 * the successive values of an operator applied to
307 * the range {@code [0..VLENGTH-1]}.
308 *
309 * <p> For each shuffle lane, where {@code N} is the shuffle lane
310 * index, the {@code N}th index value is validated
311 * against the species {@code VLENGTH}, and (if invalid)
312 * is partially wrapped to an exceptional index in the
313 * range {@code [-VLENGTH..-1]}.
314 *
315 * <p> Care should be taken to ensure {@code VectorShuffle} values
316 * produced from this method are consumed as constants to ensure
317 * optimal generation of code. For example, shuffle values can be
318 * held in {@code static final} fields or loop-invariant local variables.
319 *
320 * <p> This method behaves as if a shuffle is created from an array of
321 * mapped indexes as follows:
322 * <pre>{@code
323 * int[] a = new int[species.length()];
324 * for (int i = 0; i < a.length; i++) {
325 * a[i] = fn.applyAsInt(i);
326 * }
327 * return VectorShuffle.fromArray(a, 0);
328 * }</pre>
329 *
330 * @param species shuffle species
331 * @param fn the lane index mapping function
332 * @return a shuffle of mapped indexes
333 * @see VectorSpecies#shuffleFromOp(IntUnaryOperator)
334 */
335 @ForceInline
336 public static <E> VectorShuffle<E> fromOp(VectorSpecies<E> species, IntUnaryOperator fn) {
337 AbstractSpecies<E> vsp = (AbstractSpecies<E>) species;
338 return vsp.shuffleFromOp(fn);
339 }
340
341 /**
342 * Loads a shuffle using source indexes set to sequential
343 * values starting from {@code start} and stepping
344 * by the given {@code step}.
345 * <p>
346 * This method returns the value of the expression
347 * {@code VectorShuffle.fromOp(species, i -> start + i * step)}.
348 *
349 * @param species shuffle species
350 * @param start the starting value of the source index sequence
351 * @param step the difference between adjacent source indexes
|