Interface VectorSpecies<E>

Class<E> elementType()

Returns the primitive element type of vectors of this species.

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.

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

Returns the vector mask type for this species.

int elementSize()

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

VectorShape vectorShape()

Returns the shape of vectors produced by this species.

int length()

Returns the number of lanes in a vector of this species.

int vectorBitSize()

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

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.

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

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)

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

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.

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

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

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.

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.

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.

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.

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.

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

Vector<E> fromByteArray(byte[] a, int offset, ByteOrder bo)

Loads a vector of this species from a byte array starting at an offset. 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.fromByteArray(this,a,offset,bo) or an equivalent fromByteArray method, on the vector type corresponding to this species.

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

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.

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.

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

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 Nth index value is validated against the species VLENGTH, and (if invalid) is partially wrapped to an exceptional index in the range [-VLENGTH..-1].

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].

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);
 

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].

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.

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.

int hashCode()

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