OpenJDK 1.23 · jdk.incubator.vector.VectorSpecies · APIdia, the JavaDoc alternative

Method Summary

Modifier and Type	Method and Description
public Vector<E>	Returns: a vector where all lane elements are set to the primitive value `e` broadcast(long the value to broadcast e) Returns a vector of the given species where all lane elements are set to the primitive value `e`.
public < the boxed element type of the required lane type F> VectorSpecies<F>	Returns: the same species check(Class<F> the required lane type elementType) Checks that this species has the given element type, and returns this species unchanged.
public long	Returns: `e` checkValue(long the value to be checked e) Checks that this species can represent the given element value, and returns the value unchanged.
public int	Returns: the element size, in bits elementSize() Returns the lane size, in bits, of vectors of this species.
public static int	Returns: the bit-size of `elementType`, such as 32 for `int.class` elementSize(Class<?> a vector element type (an `ETYPE`) elementType) Returns the bit-size of the given vector element type (`ETYPE`).
public Class<E>	Returns: the primitive element type (`ETYPE`) elementType() Returns the primitive element type of vectors of this species.
public boolean	Returns: whether this species is identical to some other object equals(Object obj) Indicates whether this species is identical to some other object.
public Vector<E>	Returns: a vector of the given species filled from the array fromArray(Object an array of the `ETYPE` for this species a, int the index of the first lane value to load offset) Returns a vector of this species where lane elements are initialized from the given array at the given offset.
public Vector<E>	Returns: a vector of the given species filled from the memory segment fromMemorySegment(MemorySegment the memory segment ms, long the offset into the memory segment offset, ByteOrder the intended byte order bo) Loads a vector of this species from a memory segment starting at an offset into the memory segment.
public int	Returns: a hash code value for this species hashCode() Returns a hash code value for the species, based on the vector shape and element type.
public VectorMask<E>	Returns: a mask with out-of-range lanes unset indexInRange(int the starting index offset, int the upper-bound (exclusive) of index range limit) Returns a mask of this species where only the lanes at index N such that the adjusted index `N+offset` is in the range `[0..limit-1]` are set.
public VectorMask<E>	Returns: a mask with out-of-range lanes unset indexInRange(long the starting index offset, long the upper-bound (exclusive) of index range limit) Returns a mask of this species where only the lanes at index N such that the adjusted index `N+offset` is in the range `[0..limit-1]` are set.
public VectorShuffle<E>	Returns: a shuffle of sequential lane indexes iotaShuffle(int the starting value of the source index sequence, typically `0` start, int the difference between adjacent source indexes, typically `1` step, boolean whether to wrap resulting indexes modulo `VLENGTH` wrap) Creates a shuffle using source indexes set to sequential values starting from `start` and stepping by the given `step`.
public int	Returns: the number of vector lanes length() Returns the number of lanes in a vector of this species.
public VectorMask<E>	Returns: the mask loaded from the `boolean` array loadMask(boolean[] the `boolean` array bits, int the offset into the array offset) Returns a mask of this species where lane elements are initialized from the given array at the given offset.
public int	Returns: the largest multiple of the vector length not greater than the given length loopBound(int the input length length) Loop control function which returns the largest multiple of `VLENGTH` that is less than or equal to the given `length` value.
public long	Returns: the largest multiple of the vector length not greater than the given length loopBound(long the input length length) Loop control function which returns the largest multiple of `VLENGTH` that is less than or equal to the given `length` value.
public VectorMask<E>	Returns: a mask where each lane is set or unset according to the given bit maskAll(boolean the given mask bit to be replicated 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.
public Class<? extends VectorMask<E>>	Returns: the mask type maskType() Returns the vector mask type for this species.
public static < the boxed element type E> VectorSpecies<E>	Returns: a species for the given element type and shape of(Class<E> the element type elementType, VectorShape the shape shape) Finds a species for an element type and shape.
public static < the boxed element type E> VectorSpecies<E>	Returns: a preferred species for an element type ofLargestShape(Class<E> the element type etype) Finds the largest vector species of the given element type.
public static < the boxed element type E> VectorSpecies<E>	Returns: a preferred species for this element type ofPreferred(Class<E> the element type etype) Finds the species preferred by the current platform for a given vector element type.
public int	Returns: an indication of the size change, as a signed ratio or zero partLimit(VectorSpecies<?> the proposed output species outputSpecies, boolean whether to take lane sizes into account lanewise) Given this species and a second one, reports the net expansion or contraction of a (potentially) resizing reinterpretation cast or `lane-wise conversion` from this species to the second.
public VectorShuffle<E>	Returns: a shuffle where each lane's source index is set to the given `int` value, partially wrapped if exceptional shuffleFromArray(int[] the source indexes which the shuffle will draw from sourceIndexes, int the offset into the array offset) Creates a shuffle for this species from an `int` array starting at an offset.
public VectorShuffle<E>	Returns: a shuffle of mapped indexes shuffleFromOp(IntUnaryOperator the lane index mapping function fn) Creates a shuffle for this species from the successive values of an operator applied to the range `[0..VLENGTH-1]`.
public VectorShuffle<E>	Returns: a shuffle where each lane's source index is set to the given `int` value, partially wrapped if exceptional shuffleFromValues(int... the source indexes which the shuffle will draw from sourceIndexes) Creates a shuffle for this species from a series of source indexes.
public String	Returns: a string of the form "Species[ETYPE, VLENGTH, SHAPE]" toString() Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", where `ETYPE` is the primitive lane type, `VLENGTH` is the vector lane count associated with the species, and `SHAPE` is the vector shape associated with the species.
public int	Returns: the total vector size, in bits vectorBitSize() Returns the total vector size, in bits, of any vector of this species.
public int	Returns: the total vector size, in bytes vectorByteSize() Returns the total vector size, in bytes, of any vector of this species.
public VectorShape	Returns: the shape of any vectors of this species vectorShape() Returns the shape of vectors produced by this species.
public Class<? extends Vector<E>>	Returns: the vector type of this species vectorType() Returns the vector type of this species.
public < the boxed element type F> VectorSpecies<F>	Returns: a species for the new element type and the same shape withLanes(Class<F> the new element type newType) Finds a species with the given element type and the same shape as this species.
public VectorSpecies<E>	Returns: a species for the same element type and the new shape withShape(VectorShape the new shape newShape) Finds a species with the given shape and the same elementType as this species.
public Vector<E>	Returns: a zero vector of the given species zero() Returns a vector of this species where all lane elements are set to the default primitive value, `(ETYPE)0`.

Method Detail

broadcast back to summary

broadcast	back to summary
public Vector<E> broadcast(long e) Returns a vector of the given species where all lane elements are set to the primitive value `e`. This method returns the value of this expression: `EVector.broadcast(this, (ETYPE)e)`, where `EVector` is the vector class specific to the the `ETYPE` of this species. The `long` value must be accurately representable by `ETYPE`, so that `e==(long)(ETYPE)e`. Parameters e:long the value to broadcast Returns:Vector<E> a vector where all lane elements are set to the primitive value `e` Exceptions IllegalArgumentException: if the given `long` value cannot be represented by the vector species `ETYPE` See Also `Vector#broadcast(long)`, `checkValue(long)`

public Vector<E> broadcast(long e)

Returns a vector of the given species where all lane elements are set to the primitive value e.

This method returns the value of this expression: EVector.broadcast(this, (ETYPE)e), where EVector is the vector class specific to the the ETYPE of this species. The long value must be accurately representable by ETYPE, so that e==(long)(ETYPE)e.

Parameters

e:long: the value to broadcast

Returns:Vector<E>

a vector where all lane elements are set to the primitive value e

Exceptions

IllegalArgumentException:: if the given long value cannot be represented by the vector species ETYPE

check back to summary

check	back to summary
public <F> VectorSpecies<F> check(Class<F> elementType) 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()`. Parameters <F> the boxed element type of the required lane type elementType:Class<F> the required lane type Returns:VectorSpecies<F> the same species Exceptions ClassCastException: if the species has the wrong element type See Also `Vector#check(Class)`, `Vector#check(VectorSpecies)`

public <F> VectorSpecies<F> check(Class<F> elementType)

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().

Parameters

<F>: the boxed element type of the required lane type
elementType:Class<F>: the required lane type

Returns:VectorSpecies<F>

the same species

Exceptions

ClassCastException:: if the species has the wrong element type

checkValue back to summary

checkValue	back to summary
public long checkValue(long e) Checks that this species can represent the given element value, and returns the value unchanged. The `long` value must be accurately representable by the `ETYPE` of the vector species, so that `e==(long)(ETYPE)e`. The effect is similar to this pseudocode: `e == (long)(ETYPE)e ? e : throw new IllegalArgumentException()`. Parameters e:long the value to be checked Returns:long `e` Exceptions IllegalArgumentException: if the given `long` value cannot be represented by the vector species `ETYPE` See Also `broadcast(long)`

public long checkValue(long e)

Checks that this species can represent the given element value, and returns the value unchanged. The long value must be accurately representable by the ETYPE of the vector species, so that e==(long)(ETYPE)e. The effect is similar to this pseudocode: e == (long)(ETYPE)e ? e : throw new IllegalArgumentException().

Parameters

e:long: the value to be checked

Returns:long

e

Exceptions

IllegalArgumentException:: if the given long value cannot be represented by the vector species ETYPE

See Also

broadcast(long)

elementSize	back to summary
public int elementSize() Returns the lane size, in bits, of vectors of this species. Returns:int the element size, in bits

elementSize

back to summary

public int elementSize()

Returns the lane size, in bits, of vectors of this species.

Returns:int: the element size, in bits

elementSize back to summary

elementSize	back to summary
public static int elementSize(Class<?> elementType) Returns the bit-size of the given vector element type (`ETYPE`). The element type must be a valid `ETYPE`, not a wrapper type or other object type. The element type argument must be a mirror for a valid vector `ETYPE`, such as `byte.class`, `int.class`, or `double.class`. The bit-size of such a type is the `SIZE` constant for the corresponding wrapper class, such as `Byte.SIZE`, or `Integer.SIZE`, or `Double.SIZE`. Parameters elementType:Class<?> a vector element type (an `ETYPE`) Returns:int the bit-size of `elementType`, such as 32 for `int.class` Exceptions IllegalArgumentException: if the given `elementType` argument is not a valid vector `ETYPE`

public static int elementSize(Class<?> elementType)

Returns the bit-size of the given vector element type (ETYPE). The element type must be a valid ETYPE, not a wrapper type or other object type. The element type argument must be a mirror for a valid vector ETYPE, such as byte.class, int.class, or double.class. The bit-size of such a type is the SIZE constant for the corresponding wrapper class, such as Byte.SIZE, or Integer.SIZE, or Double.SIZE.

Parameters

elementType:Class<?>: a vector element type (an ETYPE)

Returns:int

the bit-size of elementType, such as 32 for int.class

Exceptions

IllegalArgumentException:: if the given elementType argument is not a valid vector ETYPE

elementType back to summary

elementType	back to summary
public Class<E> elementType() Returns the primitive element type of vectors of this species. Returns:Class<E> the primitive element type (`ETYPE`) See Also `Class#arrayType()`

public Class<E> elementType()

Returns the primitive element type of vectors of this species.

Returns:Class<E>: the primitive element type (ETYPE)
See Also: Class#arrayType()

equals	back to summary
public boolean equals(Object obj) 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. Returns:boolean whether this species is identical to some other object Annotations @Override

equals

back to summary

public boolean equals(Object obj)

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.

Returns:boolean

whether this species is identical to some other object

Annotations

@Override

fromArray back to summary

fromArray	back to summary
public Vector<E> fromArray(Object a, int offset) 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 correct `ETYPE`. Equivalent to `IntVector.fromArray(this,a,offset)` or an equivalent `fromArray` method, on the vector type corresponding to this species. Parameters a:Object an array of the `ETYPE` for this species offset:int the index of the first lane value to load Returns:Vector<E> a vector of the given species filled from the array Exceptions IndexOutOfBoundsException: if `offset+N < 0` or `offset+N >= a.length` for any lane `N` in the vector See Also `IntVector#fromArray(VectorSpecies, int[], int)`, `FloatVector#fromArray(VectorSpecies, float[], int)`

public Vector<E> fromArray(Object a, int offset)

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 correct ETYPE. Equivalent to IntVector.fromArray(this,a,offset) or an equivalent fromArray method, on the vector type corresponding to this species.

Parameters

a:Object: an array of the ETYPE for this species
offset:int: the index of the first lane value to load

Returns:Vector<E>

a vector of the given species filled from the array

Exceptions

IndexOutOfBoundsException:: if offset+N < 0 or offset+N >= a.length for any lane N in the vector

fromMemorySegment back to summary

fromMemorySegment	back to summary
public Vector<E> fromMemorySegment(MemorySegment ms, long offset, ByteOrder bo) Loads a vector of this species from a memory segment 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:MemorySegment the memory segment offset:long the offset into the memory segment bo:ByteOrder the intended byte order Returns:Vector<E> a vector of the given species filled from the memory segment Exceptions IndexOutOfBoundsException: if `offset+NESIZE < 0` or `offset+(N+1)ESIZE > a.length` for any lane `N` in the vector Since 19 See Also `IntVector#fromMemorySegment(VectorSpecies, java.lang.foreign.MemorySegment, long, java.nio.ByteOrder)`, `FloatVector#fromMemorySegment(VectorSpecies, java.lang.foreign.MemorySegment, long, java.nio.ByteOrder)`

public Vector<E> fromMemorySegment(MemorySegment ms, long offset, ByteOrder bo)

Loads a vector of this species from a memory segment 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:MemorySegment: the memory segment
offset:long: the offset into the memory segment
bo:ByteOrder: the intended byte order

Returns:Vector<E>

a vector of the given species filled from the memory segment

Exceptions

IndexOutOfBoundsException:: if offset+N*ESIZE < 0 or offset+(N+1)*ESIZE > a.length for any lane N in the vector

Since

hashCode	back to summary
public int hashCode() Returns a hash code value for the species, based on the vector shape and element type. Returns:int a hash code value for this species Annotations @Override

hashCode

back to summary

public int hashCode()

Returns a hash code value for the species, based on the vector shape and element type.

Returns:int

a hash code value for this species

Annotations

@Override

indexInRange back to summary

indexInRange	back to summary
public VectorMask<E> indexInRange(int offset, int limit) Returns a mask of this species where only the lanes at index N such that the adjusted index `N+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:int the starting index limit:int the upper-bound (exclusive) of index range Returns:VectorMask<E> a mask with out-of-range lanes unset See Also `VectorMask#indexInRange(int, int)`

public VectorMask<E> indexInRange(int offset, int limit)

Returns a mask of this species where only the lanes at index N such that the adjusted index N+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:int: the starting index
limit:int: the upper-bound (exclusive) of index range

Returns:VectorMask<E>

a mask with out-of-range lanes unset

See Also

VectorMask#indexInRange(int, int)

indexInRange back to summary

indexInRange	back to summary
public VectorMask<E> indexInRange(long offset, long limit) Returns a mask of this species where only the lanes at index N such that the adjusted index `N+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:long the starting index limit:long the upper-bound (exclusive) of index range Returns:VectorMask<E> a mask with out-of-range lanes unset Since 19 See Also `VectorMask#indexInRange(long, long)`

public VectorMask<E> indexInRange(long offset, long limit)

Returns a mask of this species where only the lanes at index N such that the adjusted index N+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:long: the starting index
limit:long: the upper-bound (exclusive) of index range

Returns:VectorMask<E>

a mask with out-of-range lanes unset

Since

See Also

VectorMask#indexInRange(long, long)

iotaShuffle back to summary

iotaShuffle	back to summary
public VectorShuffle<E> iotaShuffle(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 `VectorSpecies.shuffleFromOp(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 start:int the starting value of the source index sequence, typically `0` step:int the difference between adjacent source indexes, typically `1` wrap:boolean whether to wrap resulting indexes modulo `VLENGTH` Returns:VectorShuffle<E> a shuffle of sequential lane indexes See Also `VectorShuffle#iota(VectorSpecies, int, int, boolean)`

public VectorShuffle<E> iotaShuffle(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 VectorSpecies.shuffleFromOp(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

start:int: the starting value of the source index sequence, typically 0
step:int: the difference between adjacent source indexes, typically 1
wrap:boolean: whether to wrap resulting indexes modulo VLENGTH

Returns:VectorShuffle<E>

a shuffle of sequential lane indexes

length	back to summary
public 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:int the number of vector lanes

length

back to summary

public 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:int: the number of vector lanes

loadMask back to summary

loadMask	back to summary
public VectorMask<E> loadMask(boolean[] bits, int offset) Returns a mask of this species where lane elements are initialized from the given array at the given offset. Equivalent to `VectorMask.fromArray(this,a,offset)`. Parameters bits:boolean[] the `boolean` array offset:int the offset into the array Returns:VectorMask<E> the mask loaded from the `boolean` array Exceptions IndexOutOfBoundsException: if `offset+N < 0` or `offset+N >= a.length` for any lane `N` in the vector mask See Also `VectorMask#fromArray(VectorSpecies, boolean[], int)`

public VectorMask<E> loadMask(boolean[] bits, int offset)

Returns a mask of this species where lane elements are initialized from the given array at the given offset. Equivalent to VectorMask.fromArray(this,a,offset).

Parameters

bits:boolean[]: the boolean array
offset:int: the offset into the array

Returns:VectorMask<E>

the mask loaded from the boolean array

Exceptions

IndexOutOfBoundsException:: if offset+N < 0 or offset+N >= a.length for any lane N in the vector mask

loopBound back to summary

loopBound	back to summary
public int loopBound(int length) Loop control function which returns the largest multiple of `VLENGTH` that is less than or equal to the given `length` value. Here, `VLENGTH` is the result of `this.length()`, and `length` is interpreted as a number of lanes. The resulting value `R` satisfies this inequality: `R <= length < R+VLENGTH` Specifically, this method computes `length - floorMod(length, VLENGTH)`, where `floorMod` computes a remainder value by rounding its quotient toward negative infinity. As long as `VLENGTH` is a power of two, then the result is also equal to `length & ~(VLENGTH - 1)`. Parameters length:int the input length Returns:int the largest multiple of the vector length not greater than the given length Exceptions IllegalArgumentException: if the `length` is negative and the result would overflow to a positive value See Also `Math#floorMod(int, int)`

public int loopBound(int length)

Loop control function which returns the largest multiple of VLENGTH that is less than or equal to the given length value. Here, VLENGTH is the result of this.length(), and length is interpreted as a number of lanes. The resulting value R satisfies this inequality:

R <= length < R+VLENGTH

Specifically, this method computes length - floorMod(length, VLENGTH), where floorMod computes a remainder value by rounding its quotient toward negative infinity. As long as VLENGTH is a power of two, then the result is also equal to length & ~(VLENGTH - 1).

Parameters

length:int: the input length

Returns:int

the largest multiple of the vector length not greater than the given length

Exceptions

IllegalArgumentException:: if the length is negative and the result would overflow to a positive value

See Also

Math#floorMod(int, int)

loopBound back to summary

loopBound	back to summary
public long loopBound(long length) Loop control function which returns the largest multiple of `VLENGTH` that is less than or equal to the given `length` value. Here, `VLENGTH` is the result of `this.length()`, and `length` is interpreted as a number of lanes. The resulting value `R` satisfies this inequality: `R <= length < R+VLENGTH` Specifically, this method computes `length - floorMod(length, VLENGTH)`, where `floorMod` computes a remainder value by rounding its quotient toward negative infinity. As long as `VLENGTH` is a power of two, then the result is also equal to `length & ~(VLENGTH - 1)`. Parameters length:long the input length Returns:long the largest multiple of the vector length not greater than the given length Exceptions IllegalArgumentException: if the `length` is negative and the result would overflow to a positive value Since 19 See Also `Math#floorMod(long, int)`

public long loopBound(long length)

R <= length < R+VLENGTH

Parameters

length:long: the input length

Returns:long

the largest multiple of the vector length not greater than the given length

Exceptions

IllegalArgumentException:: if the length is negative and the result would overflow to a positive value

Since

See Also

Math#floorMod(long, int)

maskAll back to summary

maskAll	back to summary
public VectorMask<E> 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. Parameters bit:boolean the given mask bit to be replicated Returns:VectorMask<E> a mask where each lane is set or unset according to the given bit See Also `Vector#maskAll(boolean)`

public VectorMask<E> 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.

Parameters

bit:boolean: the given mask bit to be replicated

Returns:VectorMask<E>

a mask where each lane is set or unset according to the given bit

See Also

Vector#maskAll(boolean)

maskType	back to summary
public Class<? extends VectorMask<E>> maskType() Returns the vector mask type for this species. Returns:Class<? extends VectorMask<E>> the mask type

maskType

back to summary

public Class<? extends VectorMask<E>> maskType()

Returns the vector mask type for this species.

Returns:Class<? extends VectorMask<E>>: the mask type

of back to summary

of	back to summary
public static <E> VectorSpecies<E> of(Class<E> elementType, VectorShape shape) Finds a species for an element type and shape. Parameters <E> the boxed element type elementType:Class<E> the element type shape:VectorShape the shape Returns:VectorSpecies<E> a species for the given element type and shape Exceptions IllegalArgumentException: if no such species exists for the given combination of element type and shape or if the given type is not a valid `ETYPE` See Also `withLanes(Class)`, `withShape(VectorShape)`

public static <E> VectorSpecies<E> of(Class<E> elementType, VectorShape shape)

Finds a species for an element type and shape.

Parameters

<E>: the boxed element type
elementType:Class<E>: the element type
shape:VectorShape: the shape

Returns:VectorSpecies<E>

a species for the given element type and shape

Exceptions

IllegalArgumentException:: if no such species exists for the given combination of element type and shape or if the given type is not a valid ETYPE

ofLargestShape back to summary

ofLargestShape	back to summary
public static <E> VectorSpecies<E> ofLargestShape(Class<E> etype) 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. Parameters <E> the boxed element type etype:Class<E> the element type Returns:VectorSpecies<E> a preferred species for an element type Exceptions IllegalArgumentException: if no such species exists for the element type or if the given type is not a valid `ETYPE` See Also `VectorSpecies#ofPreferred(Class)`

public static <E> VectorSpecies<E> ofLargestShape(Class<E> etype)

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.

Parameters

<E>: the boxed element type
etype:Class<E>: the element type

Returns:VectorSpecies<E>

a preferred species for an element type

Exceptions

IllegalArgumentException:: if no such species exists for the element type or if the given type is not a valid ETYPE

See Also

VectorSpecies#ofPreferred(Class)

ofPreferred back to summary

ofPreferred	back to summary
public static <E> VectorSpecies<E> ofPreferred(Class<E> etype) Finds the species preferred by the current platform for a given vector element type. This is the same value as `VectorSpecies.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` and `ofPreferred`, because the preferred shape is usually also the largest available shape for every lane type. Therefore, most vector algorithms will perform well without `ofLargestShape`. Parameters <E> the boxed element type etype:Class<E> the element type Returns:VectorSpecies<E> a preferred species for this element type Exceptions IllegalArgumentException: if no such species exists for the element type or if the given type is not a valid `ETYPE` See Also `Vector#reinterpretShape(VectorSpecies, int)`, `VectorShape#preferredShape()`, `VectorSpecies#ofLargestShape(Class)`

public static <E> VectorSpecies<E> ofPreferred(Class<E> etype)

Finds the species preferred by the current platform for a given vector element type. This is the same value as VectorSpecies.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 and ofPreferred, because the preferred shape is usually also the largest available shape for every lane type. Therefore, most vector algorithms will perform well without ofLargestShape.

Parameters

<E>: the boxed element type
etype:Class<E>: the element type

Returns:VectorSpecies<E>

a preferred species for this element type

Exceptions

IllegalArgumentException:: if no such species exists for the element type or if the given type is not a valid ETYPE

partLimit back to summary

partLimit	back to summary
public 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 or `lane-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, if `lanewise` 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 input `VSHAPE`. If `lanewise` is true, the logical result size is the product of the input `VLENGTH` times the size of the output `ETYPE`. 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:VectorSpecies<?> the proposed output species lanewise:boolean whether to take lane sizes into account Returns:int an indication of the size change, as a signed ratio or zero See Also `Vector#reinterpretShape(VectorSpecies, int)`, `Vector#convertShape(VectorOperators.Conversion, VectorSpecies, int)`

public 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 or lane-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, if lanewise 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 input VSHAPE. If lanewise is true, the logical result size is the product of the input VLENGTH times the size of the output ETYPE.
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:VectorSpecies<?>: the proposed output species
lanewise:boolean: whether to take lane sizes into account

Returns:int

an indication of the size change, as a signed ratio or zero

shuffleFromArray back to summary

shuffleFromArray	back to summary
public VectorShuffle<E> shuffleFromArray(int[] sourceIndexes, int offset) Creates a shuffle for this 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 `i + N` is validated against the species `VLENGTH`, and (if invalid) is partially wrapped to an exceptional index in the range `[-VLENGTH..-1]`. Parameters 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 Exceptions IndexOutOfBoundsException: if `offset < 0`, or `offset > sourceIndexes.length - VLENGTH` See Also `VectorShuffle#fromArray(VectorSpecies, int[], int)`

public VectorShuffle<E> shuffleFromArray(int[] sourceIndexes, int offset)

Creates a shuffle for this 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 i + N is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1].

Parameters

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

Exceptions

IndexOutOfBoundsException:: if offset < 0, or offset > sourceIndexes.length - VLENGTH

shuffleFromOp back to summary

shuffleFromOp	back to summary
public VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn) 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, the `N`th 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[VLENGTH]; for (int i = 0; i < a.length; i++) { a[i] = fn.applyAsInt(i); } return VectorShuffle.fromArray(this, a, 0);` Parameters fn:IntUnaryOperator the lane index mapping function Returns:VectorShuffle<E> a shuffle of mapped indexes See Also `VectorShuffle#fromOp(VectorSpecies, IntUnaryOperator)`

public VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn)

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, 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[VLENGTH];
  for (int i = 0; i < a.length; i++) {
      a[i] = fn.applyAsInt(i);
  }
  return VectorShuffle.fromArray(this, a, 0);

Parameters

fn:IntUnaryOperator: the lane index mapping function

Returns:VectorShuffle<E>

a shuffle of mapped indexes

shuffleFromValues back to summary

shuffleFromValues	back to summary
public VectorShuffle<E> shuffleFromValues(int... sourceIndexes) Creates a shuffle for this species from a series of source indexes. For each shuffle lane, where `N` is the shuffle lane index, the `N`th index value is validated against the species `VLENGTH`, and (if invalid) is partially wrapped to an exceptional index in the range `[-VLENGTH..-1]`. Parameters 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 Exceptions IndexOutOfBoundsException: if `sourceIndexes.length != VLENGTH` See Also `VectorShuffle#fromValues(VectorSpecies, int...)`

public VectorShuffle<E> shuffleFromValues(int... sourceIndexes)

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

Parameters

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

Exceptions

IndexOutOfBoundsException:: if sourceIndexes.length != VLENGTH

toString back to summary

toString	back to summary
public String toString() Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", where `ETYPE` is the primitive lane type, `VLENGTH` is the vector lane count associated with the species, and `SHAPE` is the vector shape associated with the species. Returns:String a string of the form "Species[ETYPE, VLENGTH, SHAPE]" Annotations @Override

public String toString()

Returns a string of the form "Species[ETYPE, VLENGTH, SHAPE]", where ETYPE is the primitive lane type, VLENGTH is the vector lane count associated with the species, and SHAPE is the vector shape associated with the species.

Returns:String

a string of the form "Species[ETYPE, VLENGTH, SHAPE]"

Annotations

@Override

vectorBitSize back to summary

vectorBitSize	back to summary
public int vectorBitSize() Returns the total vector size, in bits, of any vector of this species. This is the same value as `this.vectorShape().vectorBitSize()`. API Note This size may be distinct from the size in bits of a mask or shuffle of this species. Returns:int the total vector size, in bits

public int vectorBitSize()

Returns the total vector size, in bits, of any vector of this species. This is the same value as this.vectorShape().vectorBitSize().

API Note

This size may be distinct from the size in bits of a mask or shuffle of this species.

Returns:int: the total vector size, in bits

vectorByteSize back to summary

vectorByteSize	back to summary
public int vectorByteSize() Returns the total vector size, in bytes, of any vector of this species. This is the same value as `this.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:int the total vector size, in bytes

public int vectorByteSize()

Returns the total vector size, in bytes, of any vector of this species. This is the same value as this.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:int: the total vector size, in bytes

vectorShape	back to summary
public VectorShape vectorShape() Returns the shape of vectors produced by this species. Returns:VectorShape the shape of any vectors of this species

vectorShape

back to summary

public VectorShape vectorShape()

Returns the shape of vectors produced by this species.

Returns:VectorShape: the shape of any vectors of this species

vectorType	back to summary
public Class<? extends Vector<E>> 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:Class<? extends Vector<E>> the vector type of this species

vectorType

back to summary

public Class<? extends Vector<E>> 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:Class<? extends Vector<E>>: the vector type of this species

withLanes back to summary

withLanes	back to summary
public <F> VectorSpecies<F> withLanes(Class<F> newType) Finds a species with the given element type and the same shape as this species. Returns the same value as `VectorSpecies.of(newType, this.vectorShape())`. Parameters <F> the boxed element type newType:Class<F> the new element type Returns:VectorSpecies<F> a species for the new element type and the same shape Exceptions IllegalArgumentException: if no such species exists for the given combination of element type and shape or if the given type is not a valid `ETYPE` See Also `withShape(VectorShape)`, `VectorSpecies#of(Class, VectorShape)`

public <F> VectorSpecies<F> withLanes(Class<F> newType)

Finds a species with the given element type and the same shape as this species. Returns the same value as VectorSpecies.of(newType, this.vectorShape()).

Parameters

<F>: the boxed element type
newType:Class<F>: the new element type

Returns:VectorSpecies<F>

a species for the new element type and the same shape

Exceptions

IllegalArgumentException:: if no such species exists for the given combination of element type and shape or if the given type is not a valid ETYPE

withShape back to summary

withShape	back to summary
public VectorSpecies<E> withShape(VectorShape newShape) Finds a species with the given shape and the same elementType as this species. Returns the same value as `VectorSpecies.of(this.elementType(), newShape)`. Parameters newShape:VectorShape the new shape Returns:VectorSpecies<E> a species for the same element type and the new shape Exceptions IllegalArgumentException: if no such species exists for the given combination of element type and shape See Also `withLanes(Class)`, `VectorSpecies#of(Class, VectorShape)`

public VectorSpecies<E> withShape(VectorShape newShape)

Finds a species with the given shape and the same elementType as this species. Returns the same value as VectorSpecies.of(this.elementType(), newShape).

Parameters

newShape:VectorShape: the new shape

Returns:VectorSpecies<E>

a species for the same element type and the new shape

Exceptions

IllegalArgumentException:: if no such species exists for the given combination of element type and shape

zero back to summary

zero	back to summary
public Vector<E> zero() Returns a vector of this species where all lane elements are set to the default primitive value, `(ETYPE)0`. Equivalent to `IntVector.zero(this)` or an equivalent `zero` method, on the vector type corresponding to this species. Returns:Vector<E> a zero vector of the given species See Also `IntVector#zero(VectorSpecies)`, `FloatVector#zero(VectorSpecies)`

public Vector<E> zero()

Returns a vector of this species where all lane elements are set to the default primitive value, (ETYPE)0. Equivalent to IntVector.zero(this) or an equivalent zero method, on the vector type corresponding to this species.

Returns:Vector<E>: a zero vector of the given species
See Also: IntVector#zero(VectorSpecies), FloatVector#zero(VectorSpecies)

public Interface VectorSpecies<E>

Method Summary

Method Detail