Class VectorShuffle<E>

public abstract class VectorShuffle<E> extends jdk.internal.vm.vector.VectorSupport.VectorShuffle<E>

A VectorShuffle represents an ordered immutable sequence of int values called source indexes, where each source index numerically selects a source lane from a compatible Vector.

A VectorShuffle and Vector of the same element type (ETYPE) and shape have the same number of lanes, and are therefore compatible (specifically, their vector species are compatible).

A shuffle is applied to a (compatible) source vector with the rearrange method.

A shuffle has a lane structure derived from its vector species, but it stores lane indexes, as ints, rather than lane values.

This method gathers lane values by random access to the source vector, selecting lanes by consulting the source indexes. If a source index appears more than once in a shuffle, then the selected lane's value is copied more than once into the result. If a particular lane is never selected by a source index, that lane's value is ignored. The resulting vector contains all the source lane values selected by the source indexes of the shuffle. The resulting lane values are ordered according to the shuffle's source indexes, not according to the original vector's lane order.

Each shuffle has a vectorSpecies() property which determines the compatibility of vectors the shuffle operates on. This ensures that the length() of a shuffle is always equal to the VLENGTH of any vector it operates on. The element type and shape of the shuffle's species are not directly relevant to the behavior of the shuffle. Shuffles can easily be converted to other lane types, as long as the lane count stays constant.

In its internal state, a shuffle always holds integral values in a narrow range from [-VLENGTH..VLENGTH-1]. The positive numbers are self-explanatory; they are lane numbers applied to any source vector. The negative numbers, when present, are a sign that the shuffle was created from a raw integer value which was not a valid lane index.

An invalid source index, represented in a shuffle by a negative number, is called an exceptional index.

Exceptional indexes are processed in a variety of ways:

• Unless documented otherwise, shuffle-using methods will throw ArrayIndexOutOfBoundsException when a lane is processed by an exceptional index.
• When an invalid source index (negative or not) is first loaded into a shuffle, it is partially normalized to the negative range of [-VLENGTH..-1] as if by wrapIndex(). This treatment of exceptional indexes is called partial wrapping, because it preserves the distinction between normal and exceptional indexes, while wrapping them into adjacent ranges of positive and non-positive numbers. A partially wrapped index can later on be fully wrapped into the positive range by adding a final offset of VLENGTH.
• In some applications, exceptional indexes used to "steer" access to a second source vector. In those cases, the exception index values, which are in the range [-VLENGTH..-1], are cycled up to the valid range [0..VLENGTH-1] and used on the second source vector.
• When a shuffle is cast from another shuffle species with a smaller VLENGTH, all indexes are re-validated against the new VLENGTH, and some may be converted to exceptional indexes. In any case, shuffle casting never converts exceptional indexes to normal ones.

Value-based classes and identity operations

VectorShuffle, along with Vector is a value-based class. Identity-sensitive operations such as == may yield unpredictable results, or reduced performance. Also, vector shuffle objects can be stored in locals and parameters and as static final constants, but storing them in other Java fields or in array elements, while semantically valid, may incur performance penalties. Finally, vector shuffles should not be computed in loops, when possible, but instead should be stored in loop-invariant locals or as static final constants.