APIdia Launch Partner
Top Description Constructors Methods
jdk.incubator.vector

public abstract sealed Class VectorShuffle<E>

extends VectorSupport.VectorShuffle<E>
permits AbstractShuffle<E>
Class Inheritance
Known Direct Subclasses
jdk.incubator.vector.AbstractShuffle
Annotations
@SuppressWarnings:exports
Type Parameters
<E>
the boxed version of ETYPE, the element type of a vector
Imports
jdk.internal.vm.annotation.ForceInline, java.lang.foreign.MemorySegment, .ValueLayout, java.nio.ByteOrder, java.util.Objects, .Arrays, java.util.function.IntUnaryOperator
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:

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.

Constructor Summary

AccessConstructor and Description
pack-priv
VectorShuffle(Object indices)

Method Summary

Modifier and TypeMethod and Description
public abstract <
the boxed element type of the species
F> VectorShuffle<F>

Returns:

a shuffle converted by shape and element type
cast(VectorSpecies<F>
the species of desired shuffle
species)

Converts this shuffle to a shuffle of the given species of element type F.

public abstract <
the boxed element type of the required species
F> VectorShuffle<F>

Returns:

the same shuffle
check(VectorSpecies<F>
the required species
species)

Checks that this shuffle has the given species, and returns this shuffle unchanged.

public abstract int

Returns:

index
checkIndex(int
the lane index
index)

Validation function for lane indexes which may be out of the valid range of [0..VLENGTH-1].

public abstract VectorShuffle<E>

Returns:

the current shuffle, unchanged
checkIndexes()

Apply the checkIndex() validation function to all lanes, throwing IndexOutOfBoundsException if there are any exceptional indexes in this shuffle.

public final boolean

Returns:

whether this vector is identical to some other object
equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether this shuffle is identical to some other object.

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional
fromArray(VectorSpecies<E>
shuffle species
species, int[]
the source indexes which the shuffle will draw from
sourceIndexes, int
the offset into the array
offset)

Creates a shuffle for a given species from an int array starting at an offset.

public static final <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional
fromMemorySegment(VectorSpecies<E>
the shuffle species
species, MemorySegment
the source indexes in memory which the shuffle will draw from
ms, long
the offset into the segment
offset, ByteOrder
the byte order
bo)

Loads a shuffle from a memory segment starting at an offset into the memory segment.

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle of mapped indexes
fromOp(VectorSpecies<E>
shuffle species
species, IntUnaryOperator
the lane index mapping function
fn)

Creates a shuffle for a given species from the successive values of an operator applied to the range [0..VLENGTH-1].

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional
fromValues(VectorSpecies<E>
shuffle species
species, int...
the source indexes which the shuffle will draw from
sourceIndexes)

Creates a shuffle for a given species from a series of source indexes.

public final int

Returns:

a hash code value for this shuffle
hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the shuffle, based on the lane source indexes and the vector species.

public abstract void
intoArray(int[]
the array, of type int[]
a, int
the offset into the array
offset)

Stores this shuffle into an int array starting at offset.

public abstract void
intoMemorySegment(MemorySegment
the memory segment
ms, long
the offset into the segment
offset, ByteOrder
the byte order
bo)

Stores this shuffle into a memory segment starting at an offset using explicit byte order.

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle of sequential lane indexes, possibly wrapped
iota(VectorSpecies<E>
shuffle species
species, int
the starting value of the source index sequence
start, int
the difference between adjacent source indexes
step, boolean
whether to wrap resulting indexes
wrap)

Creates a shuffle using source indexes set to sequential values starting from start and stepping by the given step.

public abstract VectorMask<E>

Returns:

a mask of lanes containing valid source indexes
laneIsValid()

Find all lanes containing valid indexes (non-negative values) and return a mask where exactly those lanes are set.

public abstract int

Returns:

the int lane element at lane index i
laneSource(int
the lane index
i)

Gets the int lane element at lane index i

public final int

Returns:

the number of shuffle lanes
length()

Returns the number of lanes processed by this shuffle.

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle which unzips 2*VLENGTH lanes into two vectors, returning the selected part
makeUnzip(VectorSpecies<E>
the shuffle species
species, int
the part number of the result (either zero or one)
part)

Creates a shuffle which will unzip the concatenation of two vectors, alternatively storing input lanes into one or the other output vector.

public static <
the boxed element type
E> VectorShuffle<E>

Returns:

a shuffle which zips two vectors into 2*VLENGTH lanes, returning the selected part
makeZip(VectorSpecies<E>
the shuffle species
species, int
the part number of the result (either zero or one)
part)

Creates a shuffle which will zip together two vectors, alternatively selecting lanes from one or the other.

public abstract VectorShuffle<E>

Returns:

the rearrangement of the lane elements of this shuffle
rearrange(VectorShuffle<E>
the shuffle controlling lane index selection
s)

Rearranges the lane elements of this shuffle selecting lane indexes controlled by another shuffle.

public abstract int[]

Returns:

an array containing the lane source indexes of this shuffle
toArray()

Returns an int array containing the lane source indexes of this shuffle.

public final String

Returns:

a string of the form "Shuffle[0,1,2...]"
toString()

Overrides java.lang.Object.toString.

Returns a string representation of this shuffle, of the form "Shuffle[0,1,2...]", reporting the source indexes in lane order.

public abstract Vector<E>

Returns:

a vector representation of this shuffle
toVector()

Converts this shuffle into a vector, creating a vector of integral values corresponding to the lane source indexes of the shuffle.

private static int
unzipIndex(int i, int vlen, int part)

public abstract VectorSpecies<E>

Returns:

the species of this shuffle
vectorSpecies()

Returns the species of this shuffle.

public abstract int

Returns:

index, adjusted to the range [0..VLENGTH-1} by an appropriate multiple of VLENGTH
wrapIndex(int
the lane index
index)

Validation function for lane indexes which may be out of the valid range of [0..VLENGTH-1].

public abstract VectorShuffle<E>

Returns:

the current shuffle, with all exceptional indexes wrapped
wrapIndexes()

Apply the wrapIndex() validation function to all lanes, replacing any exceptional indexes with wrapped normal indexes.

private static ArrayIndexOutOfBoundsException
wrongPartForZip(int part, boolean unzip)

private static int
zipIndex(int i, int vlen, int part)

Constructor Detail

VectorShuffleback to summary
pack-priv VectorShuffle(Object indices)

Method Detail

castback to summary
public abstract <F> VectorShuffle<F> cast(VectorSpecies<F> species)

Converts this shuffle to a shuffle of the given species of element type F. The various lane source indexes are unmodified. Exceptional source indexes remain exceptional and valid indexes remain valid.

Parameters
<F>
the boxed element type of the species
species:VectorSpecies<F>

the species of desired shuffle

Returns:VectorShuffle<F>

a shuffle converted by shape and element type

Exceptions
IllegalArgumentException:
if this shuffle length and the species length differ
checkback to summary
public abstract <F> VectorShuffle<F> check(VectorSpecies<F> species)

Checks that this shuffle has the given species, and returns this shuffle unchanged. The effect is similar to this pseudocode: species == vectorSpecies() ? this : throw new ClassCastException().

Parameters
<F>
the boxed element type of the required species
species:VectorSpecies<F>

the required species

Returns:VectorShuffle<F>

the same shuffle

Exceptions
ClassCastException:
if the shuffle species is wrong
See Also
Vector#check(Class), Vector#check(VectorSpecies)
checkIndexback to summary
public abstract int checkIndex(int index)

Validation function for lane indexes which may be out of the valid range of [0..VLENGTH-1]. If index is in this range, it is returned unchanged. Otherwise, an IndexOutOfBoundsException is thrown.

Parameters
index:int

the lane index

Returns:int

index

Exceptions
IndexOutOfBoundsException:
if the index is not less than VLENGTH, or is negative
See Also
wrapIndex(int), checkIndexes()
checkIndexesback to summary
public abstract VectorShuffle<E> checkIndexes()

Apply the checkIndex() validation function to all lanes, throwing IndexOutOfBoundsException if there are any exceptional indexes in this shuffle.

Returns:VectorShuffle<E>

the current shuffle, unchanged

Exceptions
IndexOutOfBoundsException:
if any lanes in this shuffle contain exceptional indexes
See Also
checkIndex(int), wrapIndexes()
equalsback to summary
public final boolean equals(Object obj)

Overrides java.lang.Object.equals.

Indicates whether this shuffle is identical to some other object. Two shuffles are identical only if they have the same species and same source indexes, in the same order.

Returns:boolean

whether this vector is identical to some other object

Annotations
@Override
fromArrayback to summary
public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] sourceIndexes, int offset)

Creates a shuffle for a given species from an int array starting at an offset.

For each shuffle lane, where N is the shuffle lane index, the array element at index offset + N is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1].

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

shuffle species

sourceIndexes:int[]

the source indexes which the shuffle will draw from

offset:int

the offset into the array

Returns:VectorShuffle<E>

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional

Annotations
@ForceInline
Exceptions
IndexOutOfBoundsException:
if offset < 0, or offset > sourceIndexes.length - VLENGTH
See Also
VectorSpecies#shuffleFromArray(int[], int)
fromMemorySegmentback to summary
public static final <E> VectorShuffle<E> fromMemorySegment(VectorSpecies<E> species, MemorySegment ms, long offset, ByteOrder bo)

Loads a shuffle from a memory segment starting at an offset into the memory segment. Bytes are composed into shuffle lanes according to the specified byte order. The shuffle is arranged into lanes according to memory ordering.

The following pseudocode illustrates the behavior: 

var slice = ms.asSlice(offset);
int[] ar = new int[species.length()];
for (int n = 0; n < ar.length; n++) {
    ar[n] = slice.getAtIndex(ValuaLayout.JAVA_INT_UNALIGNED, n);
}
VectorShuffle<E> r = VectorShuffle.fromArray(species, ar, 0);

Implementation Note

This operation is likely to be more efficient if the specified byte order is the same as the platform native order, since this method will not need to reorder the bytes of lane values.

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

the shuffle species

ms:MemorySegment

the source indexes in memory which the shuffle will draw from

offset:long

the offset into the segment

bo:ByteOrder

the byte order

Returns:VectorShuffle<E>

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional

Annotations
@ForceInline
Exceptions
IndexOutOfBoundsException:
if offset < 0, or offset > sourceIndexes.byteSize() - VLENGTH * 4
Since
25
fromOpback to summary
public static <E> VectorShuffle<E> fromOp(VectorSpecies<E> species, IntUnaryOperator fn)

Creates a shuffle for a given species from the successive values of an operator applied to the range [0..VLENGTH-1].

For each shuffle lane, where N is the shuffle lane index, the Nth index value is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1].

Care should be taken to ensure VectorShuffle values produced from this method are consumed as constants to ensure optimal generation of code. For example, shuffle values can be held in static final fields or loop-invariant 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] = fn.applyAsInt(i);
  }
  return VectorShuffle.fromArray(a, 0);
Parameters
<E>
the boxed element type
species:VectorSpecies<E>

shuffle species

fn:IntUnaryOperator

the lane index mapping function

Returns:VectorShuffle<E>

a shuffle of mapped indexes

Annotations
@ForceInline
See Also
VectorSpecies#shuffleFromOp(IntUnaryOperator)
fromValuesback to summary
public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... sourceIndexes)

Creates a shuffle for a given species from a series of source indexes.

For each shuffle lane, where N is the shuffle lane index, the Nth index value is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1].

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

shuffle species

sourceIndexes:int[]

the source indexes which the shuffle will draw from

Returns:VectorShuffle<E>

a shuffle where each lane's source index is set to the given int value, partially wrapped if exceptional

Annotations
@ForceInline
Exceptions
IndexOutOfBoundsException:
if sourceIndexes.length != VLENGTH
See Also
VectorSpecies#shuffleFromValues(int...)
hashCodeback to summary
public final int hashCode()

Overrides java.lang.Object.hashCode.

Returns a hash code value for the shuffle, based on the lane source indexes and the vector species.

Returns:int

a hash code value for this shuffle

Annotations
@Override
intoArrayback to summary
public abstract void intoArray(int[] a, int offset)

Stores this shuffle into an int array starting at offset.

For each shuffle lane N, the lane source index stored for that lane element is stored into the array element a[offset+N].

API Note

Shuffle source indexes are always in the range from -VLENGTH to VLENGTH-1.

Parameters
a:int[]

the array, of type int[]

offset:int

the offset into the array

Exceptions
IndexOutOfBoundsException:
if offset < 0 or offset > a.length - this.length()
intoMemorySegmentback to summary
public abstract void intoMemorySegment(MemorySegment ms, long offset, ByteOrder bo)

Stores this shuffle into a memory segment starting at an offset using explicit byte order.

Bytes are extracted from shuffle lanes according to the specified byte ordering. The shuffle lanes are stored according to their memory ordering.

The following pseudocode illustrates the behavior: 

int[] a = this.toArray();
var slice = ms.asSlice(offset)
for (int n = 0; n < a.length; n++) {
    slice.setAtIndex(ValueLayout.JAVA_INT_UNALIGNED, n, a[n]);
}

Implementation Note

This operation is likely to be more efficient if the specified byte order is the same as the platform native order, since this method will not need to reorder the bytes of lane values.

API Note

Shuffle source indexes are always in the range from -VLENGTH to VLENGTH-1.

Parameters
ms:MemorySegment

the memory segment

offset:long

the offset into the segment

bo:ByteOrder

the byte order

Exceptions
IndexOutOfBoundsException:
if offset < 0 or offset > a.byteSize() - this.length() * 4
IllegalArgumentException:
if the segment ms is read-only
Since
25
iotaback to summary
public static <E> VectorShuffle<E> iota(VectorSpecies<E> species, int start, int step, boolean wrap)

Creates a shuffle using source indexes set to sequential values starting from start and stepping by the given step.

This method returns the value of the expression VectorShuffle.fromOp(species, i -> R(start + i * step)), where R is wrapIndex if wrap is true, and is the identity function otherwise.

If wrap is false each index is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1]. Otherwise, if wrap is true, also reduce each index, as if by wrapIndex, to the valid range [0..VLENGTH-1].

API Note

The wrap parameter should be set to true if invalid source indexes should be wrapped. Otherwise, setting it to false allows invalid source indexes to be range-checked by later operations such as unary rearrange.

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

shuffle species

start:int

the starting value of the source index sequence

step:int

the difference between adjacent source indexes

wrap:boolean

whether to wrap resulting indexes

Returns:VectorShuffle<E>

a shuffle of sequential lane indexes, possibly wrapped

Annotations
@ForceInline
See Also
VectorSpecies#iotaShuffle(int, int, boolean)
laneIsValidback to summary
public abstract VectorMask<E> laneIsValid()

Find all lanes containing valid indexes (non-negative values) and return a mask where exactly those lanes are set.

Returns:VectorMask<E>

a mask of lanes containing valid source indexes

See Also
checkIndexes()
laneSourceback to summary
public abstract int laneSource(int i)

Gets the int lane element at lane index i

Parameters
i:int

the lane index

Returns:int

the int lane element at lane index i

lengthback to summary
public final int length()

Returns the number of lanes processed by this shuffle. This is the same as the VLENGTH of any vector it operates on.

Returns:int

the number of shuffle lanes

Annotations
@ForceInline
makeUnzipback to summary
public static <E> VectorShuffle<E> makeUnzip(VectorSpecies<E> species, int part)

Creates a shuffle which will unzip the concatenation of two vectors, alternatively storing input lanes into one or the other output vector. Since the logical result of an unzip is twice the size of either input, the expanded result is broken into two physical parts, selected by a part number. For example, unzipping two vectors [a,1,b,2][c,3,d,4] will yield a result in two parts, [a,b,c,d] and [1,2,3,4].

This method returns the value of the expression VectorShuffle.fromOp(species, i -> i*2+part.

Note that the source indexes in upper half of the shuffle will be invalid indexes (>= VLENGTH, or < 0 after partial normalization), which will select from the second vector.

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

the shuffle species

part:int

the part number of the result (either zero or one)

Returns:VectorShuffle<E>

a shuffle which unzips 2*VLENGTH lanes into two vectors, returning the selected part

Exceptions
ArrayIndexOutOfBoundsException:
if part is not zero or one
See Also
makeZip(VectorSpecies, int), Vector#rearrange(VectorShuffle, Vector)
makeZipback to summary
public static <E> VectorShuffle<E> makeZip(VectorSpecies<E> species, int part)

Creates a shuffle which will zip together two vectors, alternatively selecting lanes from one or the other. The logical result of a zip is twice the size of either input, and so the expanded result is broken into two physical parts, selected by a part number. For example, zipping two vectors [a,b,c,d] and [1,2,3,4] will yield the expanded logical result [a,1,b,2,c,3,d,4] which must be obtained in two parts, [a,1,b,2] and [c,3,d,4].

This method returns the value of the expression VectorShuffle.fromOp(species, i -> i/2 + (i%2)*VLENGTH + P, where P is part*VLENGTH/2.

s Note that the source indexes in the odd lanes of the shuffle will be invalid indexes (>= VLENGTH, or < 0 after partial normalization), which will select from the second vector.

Parameters
<E>
the boxed element type
species:VectorSpecies<E>

the shuffle species

part:int

the part number of the result (either zero or one)

Returns:VectorShuffle<E>

a shuffle which zips two vectors into 2*VLENGTH lanes, returning the selected part

Exceptions
ArrayIndexOutOfBoundsException:
if part is not zero or one
See Also
makeUnzip(VectorSpecies, int), Vector#rearrange(VectorShuffle, Vector)
rearrangeback to summary
public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s)

Rearranges the lane elements of this shuffle selecting lane indexes controlled by another shuffle.

For each lane of the specified 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:VectorShuffle<E>

the shuffle controlling lane index selection

Returns:VectorShuffle<E>

the rearrangement of the lane elements of this shuffle

toArrayback to summary
public abstract int[] toArray()

Returns an int array containing the lane source indexes of this shuffle.

This method behaves as if it stores this shuffle into an allocated array (using intoArray) and returns that array as follows: 

int[] a = new int[this.length()];
  VectorShuffle.intoArray(a, 0);
  return a;

API Note

Shuffle source indexes are always in the range from -VLENGTH to VLENGTH-1. A source index is exceptional if and only if it is negative.

Returns:int[]

an array containing the lane source indexes of this shuffle

toStringback to summary
public final String toString()

Overrides java.lang.Object.toString.

Returns a string representation of this shuffle, of the form "Shuffle[0,1,2...]", reporting the source indexes in lane order.

Returns:String

a string of the form "Shuffle[0,1,2...]"

Annotations
@Override
toVectorback to summary
public abstract Vector<E> toVector()

Converts this shuffle into a vector, creating a vector of integral values corresponding to the lane source indexes of the shuffle.

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 IntVector.fromArray(va, 0);

API Note

Shuffle source indexes are always in the range from -VLENGTH to VLENGTH-1. These values are converted to the ETYPE of the resulting vector, even if it is a floating point type.

Returns:Vector<E>

a vector representation of this shuffle

unzipIndexback to summary
private static int unzipIndex(int i, int vlen, int part)
vectorSpeciesback to summary
public abstract VectorSpecies<E> vectorSpecies()

Returns the species of this shuffle.

Returns:VectorSpecies<E>

the species of this shuffle

wrapIndexback to summary
public abstract int wrapIndex(int index)

Validation function for lane indexes which may be out of the valid range of [0..VLENGTH-1]. The index is forced into this range by adding or subtracting a suitable multiple of VLENGTH. Specifically, the index is reduced into the required range by computing the value of length-floor, where floor=vectorSpecies().loopBound(length) is the next lower multiple of VLENGTH. As long as VLENGTH is a power of two, then the reduced index also equal to index & (VLENGTH - 1).

Parameters
index:int

the lane index

Returns:int

index, adjusted to the range [0..VLENGTH-1} by an appropriate multiple of VLENGTH

See Also
VectorSpecies#loopBound(int), checkIndex(int), wrapIndexes()
wrapIndexesback to summary
public abstract VectorShuffle<E> wrapIndexes()

Apply the wrapIndex() validation function to all lanes, replacing any exceptional indexes with wrapped normal indexes.

Returns:VectorShuffle<E>

the current shuffle, with all exceptional indexes wrapped

See Also
wrapIndex(int), checkIndexes()
wrongPartForZipback to summary
private static ArrayIndexOutOfBoundsException wrongPartForZip(int part, boolean unzip)
zipIndexback to summary
private static int zipIndex(int i, int vlen, int part)