- Type Parameters:
E
- the boxed version ofETYPE
, the element type of a vector
VectorSpecies
relies on preview features of the Java platform:
VectorSpecies
refers to one or more preview APIs:MemorySegment
.
- API Note:
- User code should not implement this interface. A future release of this type may restrict implementations to be members of the same package.
- Implementation Note:
- The string representation of an instance of this interface will
be of the form "Species[ETYPE, VLENGTH, SHAPE]", where
ETYPE
is the primitive lane type,VLENGTH
is the vector lane count associated with the species, andSHAPE
is the vector shape associated with the species.Vector species 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.
-
Method Summary
Modifier and TypeMethodDescriptionbroadcast
(long e) Returns a vector of the given species where all lane elements are set to the primitive valuee
.<F> VectorSpecies
<F> Checks that this species has the given element type, and returns this species unchanged.long
checkValue
(long e) Checks that this species can represent the given element value, and returns the value unchanged.int
Returns the lane size, in bits, of vectors of this species.static int
elementSize
(Class<?> elementType) Returns the bit-size of the given vector element type (ETYPE
).Returns the primitive element type of vectors of this species.boolean
Indicates whether this species is identical to some other object.Returns a vector of this species where lane elements are initialized from the given array at the given offset.fromMemorySegment
(MemorySegmentPREVIEW ms, long offset, ByteOrder bo) Loads a vector of this species from a memory segmentPREVIEW starting at an offset into the memory segment.int
hashCode()
Returns a hash code value for the species, based on the vector shape and element type.indexInRange
(int offset, int limit) Returns a mask of this species where only the lanes at index N such that the adjusted indexN+offset
is in the range[0..limit-1]
are set.indexInRange
(long offset, long limit) Returns a mask of this species where only the lanes at index N such that the adjusted indexN+offset
is in the range[0..limit-1]
are set.iotaShuffle
(int start, int step, boolean wrap) Creates a shuffle using source indexes set to sequential values starting fromstart
and stepping by the givenstep
.int
length()
Returns the number of lanes in a vector of this species.loadMask
(boolean[] bits, int offset) Returns a mask of this species where lane elements are initialized from the given array at the given offset.int
loopBound
(int length) Loop control function which returns the largest multiple ofVLENGTH
that is less than or equal to the givenlength
value.long
loopBound
(long length) Loop control function which returns the largest multiple ofVLENGTH
that is less than or equal to the givenlength
value.maskAll
(boolean bit) Returns a mask of this species, where each lane is set or unset according to given single boolean, which is broadcast to all lanes.Class
<? extends VectorMask<E>> maskType()
Returns the vector mask type for this species.static <E> VectorSpecies
<E> of
(Class<E> elementType, VectorShape shape) Finds a species for an element type and shape.static <E> VectorSpecies
<E> ofLargestShape
(Class<E> etype) Finds the largest vector species of the given element type.static <E> VectorSpecies
<E> ofPreferred
(Class<E> etype) Finds the species preferred by the current platform for a given vector element type.int
partLimit
(VectorSpecies<?> outputSpecies, boolean lanewise) Given this species and a second one, reports the net expansion or contraction of a (potentially) resizing reinterpretation cast orlane-wise conversion
from this species to the second.shuffleFromArray
(int[] sourceIndexes, int offset) Creates a shuffle for this species from anint
array starting at an offset.Creates a shuffle for this species from the successive values of an operator applied to the range[0..VLENGTH-1]
.shuffleFromValues
(int... sourceIndexes) Creates a shuffle for this species from a series of source indexes.toString()
Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", whereETYPE
is the primitive lane type,VLENGTH
is the vector lane count associated with the species, andSHAPE
is the vector shape associated with the species.int
Returns the total vector size, in bits, of any vector of this species.int
Returns the total vector size, in bytes, of any vector of this species.Returns the shape of vectors produced by this species.Returns the vector type of this species.<F> VectorSpecies
<F> Finds a species with the given element type and the same shape as this species.withShape
(VectorShape newShape) Finds a species with the given shape and the same elementType as this species.zero()
Returns a vector of this species where all lane elements are set to the default primitive value,(ETYPE)0
.
-
Method Details
-
elementType
Returns the primitive element type of vectors of this species.- Returns:
- the primitive element type (
ETYPE
) - See Also:
-
vectorType
Returns the vector type of this species. A vector is of this species if and only if it is of the corresponding vector type.- Returns:
- the vector type of this species
-
maskType
Class<? extends VectorMask<E>> maskType()Returns the vector mask type for this species.- Returns:
- the mask type
-
elementSize
int elementSize()Returns the lane size, in bits, of vectors of this species.- Returns:
- the element size, in bits
-
vectorShape
VectorShape vectorShape()Returns the shape of vectors produced by this species.- Returns:
- the shape of any vectors of this species
-
length
int length()Returns the number of lanes in a vector of this species.- API Note:
- This is also the number of lanes in a mask or shuffle associated with a vector of this species.
- Returns:
- the number of vector lanes
-
vectorBitSize
int vectorBitSize()Returns the total vector size, in bits, of any vector of this species. This is the same value asthis.vectorShape().vectorBitSize()
.- API Note:
- This size may be distinct from the size in bits of a mask or shuffle of this species.
- Returns:
- the total vector size, in bits
-
vectorByteSize
int vectorByteSize()Returns the total vector size, in bytes, of any vector of this species. This is the same value asthis.vectorShape().vectorBitSize() / Byte.SIZE
.- API Note:
- This size may be distinct from the size in bits of a mask or shuffle of this species.
- Returns:
- the total vector size, in bytes
-
loopBound
int loopBound(int length) Loop control function which returns the largest multiple ofVLENGTH
that is less than or equal to the givenlength
value. Here,VLENGTH
is the result ofthis.length()
, andlength
is interpreted as a number of lanes. The resulting valueR
satisfies this inequality:R <= length < R+VLENGTH
Specifically, this method computes
length - floorMod(length, VLENGTH)
, wherefloorMod
computes a remainder value by rounding its quotient toward negative infinity. As long asVLENGTH
is a power of two, then the result is also equal tolength & ~(VLENGTH - 1)
.- Parameters:
length
- the input length- Returns:
- the largest multiple of the vector length not greater than the given length
- Throws:
IllegalArgumentException
- if thelength
is negative and the result would overflow to a positive value- See Also:
-
loopBound
long loopBound(long length) Loop control function which returns the largest multiple ofVLENGTH
that is less than or equal to the givenlength
value. Here,VLENGTH
is the result ofthis.length()
, andlength
is interpreted as a number of lanes. The resulting valueR
satisfies this inequality:R <= length < R+VLENGTH
Specifically, this method computes
length - floorMod(length, VLENGTH)
, wherefloorMod
computes a remainder value by rounding its quotient toward negative infinity. As long asVLENGTH
is a power of two, then the result is also equal tolength & ~(VLENGTH - 1)
.- Parameters:
length
- the input length- Returns:
- the largest multiple of the vector length not greater than the given length
- Throws:
IllegalArgumentException
- if thelength
is negative and the result would overflow to a positive value- Since:
- 19
- See Also:
-
indexInRange
Returns a mask of this species where only the lanes at index N such that the adjusted indexN+offset
is in the range[0..limit-1]
are set.This method returns the value of the expression
maskAll(true).indexInRange(offset, limit)
- Parameters:
offset
- the starting indexlimit
- the upper-bound (exclusive) of index range- Returns:
- a mask with out-of-range lanes unset
- See Also:
-
indexInRange
Returns a mask of this species where only the lanes at index N such that the adjusted indexN+offset
is in the range[0..limit-1]
are set.This method returns the value of the expression
maskAll(true).indexInRange(offset, limit)
- Parameters:
offset
- the starting indexlimit
- the upper-bound (exclusive) of index range- Returns:
- a mask with out-of-range lanes unset
- Since:
- 19
- See Also:
-
check
Checks that this species has the given element type, and returns this species unchanged. The effect is similar to this pseudocode:elementType == elementType() ? this : throw new ClassCastException()
.- Type Parameters:
F
- the boxed element type of the required lane type- Parameters:
elementType
- the required lane type- Returns:
- the same species
- Throws:
ClassCastException
- if the species has the wrong element type- See Also:
-
partLimit
Given this species and a second one, reports the net expansion or contraction of a (potentially) resizing reinterpretation cast orlane-wise conversion
from this species to the second. The sign and magnitude of the return value depends on the size difference between the proposed input and output shapes, and (optionally, iflanewise
is true) also on the size difference between the proposed input and output lanes.- First, a logical result size is determined.
If
lanewise
is false, this size that of the inputVSHAPE
. Iflanewise
is true, the logical result size is the product of the inputVLENGTH
times the size of the outputETYPE
. - Next, the logical result size is compared against the size of the proposed output shape, to see how it will fit.
- If the logical result fits precisely in the output shape, the return value is zero, signifying no net expansion or contraction.
- If the logical result would overflow the output shape, the
return value is the ratio (greater than one) of the logical
result size to the (smaller) output size. This ratio can be
viewed as measuring the proportion of "dropped input bits"
which must be deleted from the input in order for the result to
fit in the output vector. It is also the part limit,
a upper exclusive limit on the
part
parameter to a method that would transform the input species to the output species. - If the logical result would drop into the output shape
with room to spare, the return value is a negative number whose
absolute value the ratio (greater than one) between the output
size and the (smaller) logical result size. This ratio can be
viewed as measuring the proportion of "extra padding bits"
which must be added to the logical result to fill up the output
vector. It is also the part limit, an exclusive lower
limit on the
part
parameter to a method that would transform the input species to the output species.
- Parameters:
outputSpecies
- the proposed output specieslanewise
- whether to take lane sizes into account- Returns:
- an indication of the size change, as a signed ratio or zero
- See Also:
- First, a logical result size is determined.
If
-
withLanes
Finds a species with the given element type and the same shape as this species. Returns the same value asVectorSpecies.of(newType, this.vectorShape())
.- Type Parameters:
F
- the boxed element type- Parameters:
newType
- the new element type- Returns:
- a species for the new element type and the same shape
- Throws:
IllegalArgumentException
- if no such species exists for the given combination of element type and shape or if the given type is not a validETYPE
- See Also:
-
withShape
Finds a species with the given shape and the same elementType as this species. Returns the same value asVectorSpecies.of(this.elementType(), newShape)
.- Parameters:
newShape
- the new shape- Returns:
- a species for the same element type and the new shape
- Throws:
IllegalArgumentException
- if no such species exists for the given combination of element type and shape- See Also:
-
of
Finds a species for an element type and shape.- Type Parameters:
E
- the boxed element type- Parameters:
elementType
- the element typeshape
- the shape- Returns:
- a species for the given element type and shape
- Throws:
IllegalArgumentException
- if no such species exists for the given combination of element type and shape or if the given type is not a validETYPE
- See Also:
-
ofLargestShape
Finds the largest vector species of the given element type.The returned species is a species chosen by the platform that has a shape with the largest possible bit-size for the given element type. The underlying vector shape might not support other lane types on some platforms, which may limit the applicability of reinterpretation casts. Vector algorithms which require reinterpretation casts will be more portable if they use the platform's preferred species.
- Type Parameters:
E
- the boxed element type- Parameters:
etype
- the element type- Returns:
- a preferred species for an element type
- Throws:
IllegalArgumentException
- if no such species exists for the element type or if the given type is not a validETYPE
- See Also:
-
ofPreferred
Finds the species preferred by the current platform for a given vector element type. This is the same value asVectorSpecies.of(etype, VectorShape.preferredShape())
.This species is chosen by the platform so that it has the largest possible shape that supports all lane element types. This has the following implications:
- The various preferred species for different element types will have the same underlying shape.
- All vectors created from preferred species will have a common bit-size and information capacity.
- Reinterpretation casts between vectors of preferred species will neither truncate lanes nor fill them with default values.
- For any particular element type, some platform might possibly provide a larger vector shape that (as a trade-off) does not support all possible element types.
- Implementation Note:
- On many platforms there is no behavioral difference
between
ofLargestShape
andofPreferred
, because the preferred shape is usually also the largest available shape for every lane type. Therefore, most vector algorithms will perform well withoutofLargestShape
. - Type Parameters:
E
- the boxed element type- Parameters:
etype
- the element type- Returns:
- a preferred species for this element type
- Throws:
IllegalArgumentException
- if no such species exists for the element type or if the given type is not a validETYPE
- See Also:
-
elementSize
Returns the bit-size of the given vector element type (ETYPE
). The element type must be a validETYPE
, not a wrapper type or other object type. The element type argument must be a mirror for a valid vectorETYPE
, such asbyte.class
,int.class
, ordouble.class
. The bit-size of such a type is theSIZE
constant for the corresponding wrapper class, such asByte.SIZE
, orInteger.SIZE
, orDouble.SIZE
.- Parameters:
elementType
- a vector element type (anETYPE
)- Returns:
- the bit-size of
elementType
, such as 32 forint.class
- Throws:
IllegalArgumentException
- if the givenelementType
argument is not a valid vectorETYPE
-
zero
Returns a vector of this species where all lane elements are set to the default primitive value,(ETYPE)0
. Equivalent toIntVector.zero(this)
or an equivalentzero
method, on the vector type corresponding to this species.- Returns:
- a zero vector of the given species
- See Also:
-
fromArray
Returns a vector of this species where lane elements are initialized from the given array at the given offset. The array must be of the correctETYPE
. Equivalent toIntVector.fromArray(this,a,offset)
or an equivalentfromArray
method, on the vector type corresponding to this species.- Parameters:
a
- an array of theETYPE
for this speciesoffset
- the index of the first lane value to load- Returns:
- a vector of the given species filled from the array
- Throws:
IndexOutOfBoundsException
- ifoffset+N < 0
oroffset+N >= a.length
for any laneN
in the vector- See Also:
-
fromMemorySegment
Loads a vector of this species from a memory segmentPREVIEW starting at an offset into the memory segment. Bytes are composed into primitive lane elements according to the specified byte order. The vector is arranged into lanes according to memory ordering.Equivalent to
IntVector.fromMemorySegment(this,ms,offset,bo)
, on the vector type corresponding to this species.- Parameters:
ms
- the memory segmentoffset
- the offset into the memory segmentbo
- the intended byte order- Returns:
- a vector of the given species filled from the memory segment
- Throws:
IndexOutOfBoundsException
- ifoffset+N*ESIZE < 0
oroffset+(N+1)*ESIZE > a.length
for any laneN
in the vector- Since:
- 19
- See Also:
-
loadMask
Returns a mask of this species where lane elements are initialized from the given array at the given offset. Equivalent toVectorMask.fromArray(this,a,offset)
.- Parameters:
bits
- theboolean
arrayoffset
- the offset into the array- Returns:
- the mask loaded from the
boolean
array - Throws:
IndexOutOfBoundsException
- ifoffset+N < 0
oroffset+N >= a.length
for any laneN
in the vector mask- See Also:
-
maskAll
Returns a mask of this species, where each lane is set or unset according to given single boolean, which is broadcast to all lanes.- Parameters:
bit
- the given mask bit to be replicated- Returns:
- a mask where each lane is set or unset according to the given bit
- See Also:
-
broadcast
Returns a vector of the given species where all lane elements are set to the primitive valuee
.This method returns the value of this expression:
EVector.broadcast(this, (ETYPE)e)
, whereEVector
is the vector class specific to the theETYPE
of this species. Thelong
value must be accurately representable byETYPE
, so thate==(long)(ETYPE)e
.- Parameters:
e
- the value to broadcast- Returns:
- a vector where all lane elements are set to
the primitive value
e
- Throws:
IllegalArgumentException
- if the givenlong
value cannot be represented by the vector speciesETYPE
- See Also:
-
checkValue
long checkValue(long e) Checks that this species can represent the given element value, and returns the value unchanged. Thelong
value must be accurately representable by theETYPE
of the vector species, so thate==(long)(ETYPE)e
. The effect is similar to this pseudocode:e == (long)(ETYPE)e ? e : throw new IllegalArgumentException()
.- Parameters:
e
- the value to be checked- Returns:
e
- Throws:
IllegalArgumentException
- if the givenlong
value cannot be represented by the vector speciesETYPE
- See Also:
-
shuffleFromValues
Creates a shuffle for this species from a series of source indexes.For each shuffle lane, where
N
is the shuffle lane index, theN
th index value is validated against the speciesVLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range[-VLENGTH..-1]
.- Parameters:
sourceIndexes
- the source indexes which the shuffle will draw from- Returns:
- a shuffle where each lane's source index is set to the given
int
value, partially wrapped if exceptional - Throws:
IndexOutOfBoundsException
- ifsourceIndexes.length != VLENGTH
- See Also:
-
shuffleFromArray
Creates a shuffle for this species from anint
array starting at an offset.For each shuffle lane, where
N
is the shuffle lane index, the array element at indexi + N
is validated against the speciesVLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range[-VLENGTH..-1]
.- Parameters:
sourceIndexes
- the source indexes which the shuffle will draw fromoffset
- the offset into the array- Returns:
- a shuffle where each lane's source index is set to the given
int
value, partially wrapped if exceptional - Throws:
IndexOutOfBoundsException
- ifoffset < 0
, oroffset > sourceIndexes.length - VLENGTH
- See Also:
-
shuffleFromOp
Creates a shuffle for this 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, theN
th index value is validated against the speciesVLENGTH
, 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 instatic 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[VLENGTH]; for (int i = 0; i < a.length; i++) { a[i] = fn.applyAsInt(i); } return VectorShuffle.fromArray(this, a, 0);
- Parameters:
fn
- the lane index mapping function- Returns:
- a shuffle of mapped indexes
- See Also:
-
iotaShuffle
Creates a shuffle using source indexes set to sequential values starting fromstart
and stepping by the givenstep
.This method returns the value of the expression
VectorSpecies.shuffleFromOp(i -> R(start + i * step))
, whereR
iswrapIndex
ifwrap
is true, and is the identity function otherwise.If
wrap
is false each index is validated against the speciesVLENGTH
, and (if invalid) is partially wrapped to an exceptional index in the range[-VLENGTH..-1]
. Otherwise, ifwrap
is true, also reduce each index, as if bywrapIndex
, to the valid range[0..VLENGTH-1]
.- API Note:
- The
wrap
parameter should be set totrue
if invalid source indexes should be wrapped. Otherwise, setting it tofalse
allows invalid source indexes to be range-checked by later operations such asunary rearrange
. - Parameters:
start
- the starting value of the source index sequence, typically0
step
- the difference between adjacent source indexes, typically1
wrap
- whether to wrap resulting indexes moduloVLENGTH
- Returns:
- a shuffle of sequential lane indexes
- See Also:
-
toString
String toString()Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", whereETYPE
is the primitive lane type,VLENGTH
is the vector lane count associated with the species, andSHAPE
is the vector shape associated with the species. -
equals
Indicates whether this species is identical to some other object. Two species are identical only if they have the same shape and same element type. -
hashCode
int hashCode()Returns a hash code value for the species, based on the vector shape and element type.
-
VectorSpecies
when preview features are enabled.