Module jdk.incubator.vector

Package jdk.incubator.vector

Interface VectorSpecies<E>

类型参数：

E - ETYPE的装箱版本，向量的元素类型

       public interface VectorSpecies<E>
      

VectorSpecies依赖于Java平台的预览功能：

• VectorSpecies指的是一个或多个预览API：MemorySegment。

仅当启用预览功能时，程序才能使用VectorSpecies。

预览功能可能会在未来的版本中被移除，或升级为Java平台的永久功能。

管理具有相同元素类型（ETYPE）和形状的所有向量的接口。

API注释：

用户代码不应实现此接口。将来的某个版本可能会限制实现必须是同一包的成员。

实现注释：

此接口的实例的字符串表示形式将采用"Species[ETYPE, VLENGTH, SHAPE]"的形式，其中 ETYPE是原始的通道类型，VLENGTH是与该种类相关联的向量通道计数，SHAPE是与该种类相关联的向量形状。

向量种类对象可以存储在局部变量和参数中，以及作为static final常量，但将它们存储在其他Java字段或数组元素中，虽然在语义上是有效的，但可能会导致性能损失。

Method Summary

Modifier and Type	Method	Description
Vector<E>	broadcast(long e)	返回给定种类的向量，其中所有通道元素均设置为原始值e。
<F> VectorSpecies<F>	check(Class<F> elementType)	检查此种类是否具有给定的元素类型，并返回此种类不变。
long	checkValue(long e)	检查此种类是否可以表示给定的元素值，并返回该值不变。
int	elementSize()	返回此种类的向量的通道大小，以位为单位。
static int	elementSize(Class<?> elementType)	返回给定向量元素类型（ETYPE）的位大小。
Class<E>	elementType()	返回此种类的向量的原始元素类型。
boolean	equals(Object obj)	指示此种类是否与其他对象相同。
Vector<E>	fromArray(Object a, int offset)	返回此种类的向量，其中通道元素从给定数组的给定偏移量开始初始化。
Vector<E>	fromMemorySegment(MemorySegmentPREVIEW ms, long offset, ByteOrder bo)	从预览的内存段中的偏移量开始加载此种类的向量。
int	hashCode()	返回该种类的哈希码值，基于向量形状和元素类型。
VectorMask<E>	indexInRange(int offset, int limit)	返回此种类的掩码，其中仅将索引N处的通道设置为范围[0..limit-1]中的N+offset。
VectorMask<E>	indexInRange(long offset, long limit)	返回此种类的掩码，其中仅将索引N处的通道设置为范围[0..limit-1]中的N+offset。
VectorShuffle<E>	iotaShuffle(int start, int step, boolean wrap)	使用从start开始并按给定step递增的顺序值创建一个洗牌。
int	length()	返回此种类的向量中的通道数。
VectorMask<E>	loadMask(boolean[] bits, int offset)	返回此种类的掩码，其中通道元素从给定数组的给定偏移量开始初始化。
int	loopBound(int length)	循环控制函数，返回小于或等于给定length值的最大VLENGTH的倍数。
long	loopBound(long length)	循环控制函数，返回小于或等于给定length值的最大VLENGTH的倍数。
VectorMask<E>	maskAll(boolean bit)	返回此种类的掩码，其中每个通道根据给定的单个布尔值设置或取消设置，该值广播到所有通道。
Class<? extends VectorMask<E>>	maskType()	返回此种类的向量掩码类型。
static <E> VectorSpecies<E>	of(Class<E> elementType, VectorShape shape)	为元素类型和形状找到一个种类。
static <E> VectorSpecies<E>	ofLargestShape(Class<E> etype)	找到给定元素类型的最大向量种类。
static <E> VectorSpecies<E>	ofPreferred(Class<E> etype)	找到当前平台首选的给定向量元素类型的种类。
int	partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)	给定此种类和第二种类，报告从此种类到第二种类的（可能）调整大小的重新解释转换或逐通道转换的净扩展或收缩。
VectorShuffle<E>	shuffleFromArray(int[] sourceIndexes, int offset)	从偏移量开始创建此种类的洗牌int数组。
VectorShuffle<E>	shuffleFromOp(IntUnaryOperator fn)	从应用于范围[0..VLENGTH-1]的连续值的运算符创建此种类的洗牌。
VectorShuffle<E>	shuffleFromValues(int... sourceIndexes)	从一系列源索引创建此种类的洗牌。
String	toString()	返回形式为"Species[ETYPE, VLENGTH, SHAPE]"的字符串，其中ETYPE是原始的通道类型，VLENGTH是与该种类相关联的向量通道计数， SHAPE是与该种类相关联的向量形状。
int	vectorBitSize()	返回此种类的任何向量的总位大小，以位为单位。
int	vectorByteSize()	返回此种类的任何向量的总字节大小。
VectorShape	vectorShape()	返回此种类生成的向量的形状。
Class<? extends Vector<E>>	vectorType()	返回此种类的向量类型。
<F> VectorSpecies<F>	withLanes(Class<F> newType)	找到具有给定元素类型和与此种类相同形状的种类。
VectorSpecies<E>	withShape(VectorShape newShape)	找到具有给定形状和与此种类相同元素类型的种类。
Vector<E>	zero()	返回此种类的向量，其中所有通道元素均设置为默认原始值(ETYPE)0。

Method Details

elementType

             Class<E> elementType()
            

返回此种类的向量的原始元素类型。

返回：

原始元素类型（ETYPE）

参见：

• Class.arrayType()

vectorType

             Class<? extends Vector<E>> vectorType()
            

返回此种类的向量类型。只有当向量是相应向量类型时，才属于此种类。

返回：

此种类的向量类型

maskType

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

返回此种类的向量掩码类型。

返回：

掩码类型

elementSize

             int elementSize()
            

返回此种类的向量的通道大小，以位为单位。

返回：

元素大小，以位为单位

vectorShape

             VectorShape vectorShape()
            

返回此种类生成的向量的形状。

返回：

此种类的任何向量的形状

length

             int length()
            

返回此种类的向量中的通道数。

API注释：

这也是与此种类的向量相关的掩码或洗牌中的通道数。

返回：

向量通道数

vectorBitSize

             int vectorBitSize()
            

返回此种类的任何向量的总位大小，以位为单位。这与this.vectorShape().vectorBitSize()的值相同。

API注释：

此大小可能与此种类的掩码或洗牌的位大小不同。

返回：

总向量大小，以位为单位

vectorByteSize

             int vectorByteSize()
            

返回此种类的任何向量的总字节大小。这与this.vectorShape().vectorBitSize() / Byte.SIZE的值相同。

API注释：

此大小可能与此种类的掩码或洗牌的位大小不同。

返回：

总向量大小，以字节为单位

loopBound

             int loopBound(int length)
            

循环控制函数，返回小于或等于给定length值的最大VLENGTH的倍数。这里，VLENGTH是this.length()的结果，length被解释为通道数。得到的值R满足以下不等式：

R <= length < R+VLENGTH
 

具体来说，此方法计算length - floorMod(length, VLENGTH)，其中floorMod通过向负无穷大舍入其商来计算余数值。只要VLENGTH是2的幂，结果也等于length & ~(VLENGTH - 1)。

参数：

length - 输入长度

返回：

不大于给定长度的向量长度的最大倍数

抛出：

IllegalArgumentException - 如果length为负且结果会溢出为正值

参见：

• Math.floorMod(int, int)

loopBound

             long loopBound(long length)
            

循环控制函数，返回小于或等于给定length值的最大VLENGTH的倍数。这里，VLENGTH是this.length()的结果，length被解释为通道数。得到的值R满足以下不等式：

R <= length < R+VLENGTH
 

具体来说，此方法计算length - floorMod(length, VLENGTH)，其中floorMod通过向负无穷大舍入其商来计算余数值。只要VLENGTH是2的幂，结果也等于length & ~(VLENGTH - 1)。

参数:

length - 输入长度

返回:

不大于给定长度的向量长度的最大倍数

抛出:

IllegalArgumentException - 如果length为负且结果会溢出为正值

自:

19

参见:

• Math.floorMod(long, int)

indexInRange

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

返回此种类的掩码，其中仅设置索引N处的通道，使得调整后的索引N+offset在范围[0..limit-1]内。

此方法返回表达式maskAll(true).indexInRange(offset, limit)的值

参数:

offset - 起始索引

limit - 索引范围的上界（不包括）

返回:

具有超出范围通道未设置的掩码

参见:

• VectorMask.indexInRange(int, int)

indexInRange

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

返回此种类的掩码，其中仅设置索引N处的通道，使得调整后的索引N+offset在范围[0..limit-1]内。

此方法返回表达式maskAll(true).indexInRange(offset, limit)的值

参数:

offset - 起始索引

limit - 索引范围的上界（不包括）

返回:

具有超出范围通道未设置的掩码

自:

19

参见:

• VectorMask.indexInRange(long, long)

check

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

检查此种类是否具有给定的元素类型，并返回此种类不变。效果类似于此伪代码：elementType == elementType() ? this : throw new ClassCastException()。

类型参数:

F - 所需通道类型的装箱元素类型

参数:

elementType - 所需通道类型

返回:

相同的种类

抛出:

ClassCastException - 如果种类具有错误的元素类型

参见:

• Vector.check(Class)
• Vector.check(VectorSpecies)

partLimit

             int partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)
            

给定此种类和第二个种类，报告（可能）从此种类到第二个种类的调整大小的净扩展或收缩，这是通过重新解释转换或逐通道转换实现的。返回值的符号和大小取决于所提议的输入和输出形状之间的大小差异，以及（如果lanewise为true）还取决于所提议的输入和输出通道之间的大小差异。

• 首先，确定逻辑结果大小。如果lanewise为false，则此大小为输入VSHAPE的大小。如果lanewise为true，则逻辑结果大小是输入VLENGTH乘以输出ETYPE的大小。
• 接下来，将逻辑结果大小与所提议的输出形状的大小进行比较，以查看它将如何适应。
• 如果逻辑结果恰好适合输出形状，则返回值为零，表示没有净扩展或收缩。
• 如果逻辑结果会溢出输出形状，则返回值是逻辑结果大小与（较小的）输出大小的比率（大于一）。此比率可视为衡量必须从输入中删除的“丢弃输入位”的比例，以使结果适合输出向量。它还是部分限制，是将输入种类转换为输出种类的方法的part参数的上限（不包括）。
• 如果逻辑结果会掉入输出形状并有多余空间，则返回值是负数，其绝对值是输出大小与（较小的）逻辑结果大小的比率（大于一）。此比率可视为衡量必须向逻辑结果中添加的“额外填充位”的比例，以填充输出向量。它还是部分限制，是将输入种类转换为输出种类的方法的part参数的独占下限。

参数:

outputSpecies - 所提议的输出种类

lanewise - 是否考虑通道大小

返回:

表示大小变化的有符号比率或零

参见:

• Vector.reinterpretShape(VectorSpecies,int)
• Vector.convertShape(VectorOperators.Conversion,VectorSpecies,int)

withLanes

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

找到具有给定元素类型和与此种类相同形状的种类。返回与VectorSpecies.of(newType, this.vectorShape())相同的值。

类型参数:

F - 装箱元素类型

参数:

newType - 新元素类型

返回:

具有新元素类型和相同形状的种类

抛出:

IllegalArgumentException - 如果给定元素类型和形状的组合不存在相应的种类，或者给定类型不是有效的ETYPE

参见:

• withShape(VectorShape)
• of(Class, VectorShape)

withShape

             VectorSpecies<E> withShape(VectorShape newShape)
            

找到具有给定形状和与此种类相同元素类型的种类。返回与VectorSpecies.of(this.elementType(), newShape)相同的值。

参数:

newShape - 新形状

返回:

具有相同元素类型和新形状的种类

抛出:

IllegalArgumentException - 如果给定元素类型和形状的组合不存在相应的种类

参见:

• withLanes(Class)
• of(Class, VectorShape)

of

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

找到具有元素类型和形状的种类。

类型参数:

E - 装箱元素类型

参数:

elementType - 元素类型

shape - 形状

返回:

具有给定元素类型和形状的种类

抛出:

IllegalArgumentException - 如果给定元素类型和形状的组合不存在相应的种类，或者给定类型不是有效的ETYPE

参见:

• withLanes(Class)
• withShape(VectorShape)

ofLargestShape

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

找到给定元素类型的最大向量种类。

返回的种类是平台选择的具有给定元素类型的最大可能位大小的形状。在某些平台上，底层向量形状可能不支持其他通道类型，这可能限制重新解释转换的适用性。如果需要重新解释转换的向量算法将更具可移植性，如果它们使用平台的首选种类。

类型参数:

E - 装箱元素类型

参数:

etype - 元素类型

返回:

用于元素类型的首选种类

抛出:

IllegalArgumentException - 如果不存在给定元素类型的种类，或者给定类型不是有效的ETYPE

参见:

• ofPreferred(Class)

ofPreferred

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

找到当前平台首选的给定向量元素类型的种类。这与VectorSpecies.of(etype, VectorShape.preferredShape())的值相同。

此种类由平台选择，以便具有支持所有通道元素类型的最大可能形状。这具有以下含义：

• 不同元素类型的各种首选种类将具有相同的底层形状。
• 所有从首选种类创建的向量将具有共同的位大小和信息容量。
• 首选种类之间的重新解释转换既不会截断通道也不会用默认值填充它们。
• 对于任何特定元素类型，某些平台可能提供更大的向量形状（作为一种权衡），该形状不支持所有可能的元素类型。

实现注意事项:

在许多平台上，ofLargestShape和ofPreferred之间没有行为差异，因为首选形状通常也是每个通道类型的最大可用形状。因此，大多数矢量算法在没有ofLargestShape的情况下也会表现良好。

类型参数:

E - 装箱元素类型

参数:

etype - 元素类型

返回:

此元素类型的首选种类

抛出:

IllegalArgumentException - 如果不存在该元素类型的种类，或者给定类型不是有效的ETYPE

参见:

• Vector.reinterpretShape(VectorSpecies,int)
• VectorShape.preferredShape()
• ofLargestShape(Class)

elementSize

             static int elementSize(Class<?> elementType)
            

返回给定矢量元素类型（ETYPE）的位大小。元素类型必须是有效的ETYPE，而不是包装类型或其他对象类型。元素类型参数必须是有效矢量ETYPE的镜像，例如byte.class，int.class或double.class。这种类型的位大小是相应包装类的SIZE常量，例如Byte.SIZE，或Integer.SIZE，或Double.SIZE。

参数:

elementType - 矢量元素类型（一个ETYPE）

返回:

elementType的位大小，例如int.class为32

抛出:

IllegalArgumentException - 如果给定的elementType参数不是有效的矢量ETYPE

zero

             Vector<E> zero()
            

返回此种类的矢量，其中所有通道元素都设置为默认的原始值(ETYPE)0。等同于IntVector.zero(this)或相应于此种类的矢量类型的等效zero方法。

返回:

给定种类的零矢量

参见:

• IntVector.zero(VectorSpecies)
• FloatVector.zero(VectorSpecies)

fromArray

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

返回此种类的矢量，其中通道元素从给定数组的给定偏移初始化。数组必须是正确的ETYPE。等同于IntVector.fromArray(this,a,offset)或相应于此种类的矢量类型的等效fromArray方法。

参数:

a - 此种类的ETYPE数组

offset - 要加载的第一个通道值的索引

返回:

从数组填充的给定种类的矢量

抛出:

IndexOutOfBoundsException - 如果对于矢量中的任何通道N，offset+N < 0或offset+N >= a.length

参见:

• IntVector.fromArray(VectorSpecies,int[],int)
• FloatVector.fromArray(VectorSpecies,float[],int)

fromMemorySegment

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

从memory segment中加载此种类的矢量^PREVIEW，从内存段的偏移开始。字节根据指定的字节顺序组成原始通道元素。矢量根据内存排序排列。

等同于IntVector.fromMemorySegment(this,ms,offset,bo)，对应于此种类的矢量类型。

参数:

ms - 内存段

offset - 进入内存段的偏移量

bo - 预期的字节顺序

返回:

从内存段填充的给定种类的矢量

抛出:

IndexOutOfBoundsException - 如果对于矢量中的任何通道N，offset+N*ESIZE < 0或offset+(N+1)*ESIZE > a.length

自:

19

参见:

• IntVector.fromMemorySegment(VectorSpecies, java.lang.foreign.MemorySegment, long, java.nio.ByteOrder)^PREVIEW
• FloatVector.fromMemorySegment(VectorSpecies, java.lang.foreign.MemorySegment, long, java.nio.ByteOrder)^PREVIEW

loadMask

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

返回此种类的掩码，其中通道元素从给定数组的给定偏移初始化。等同于VectorMask.fromArray(this,a,offset)。

参数:

bits - boolean数组

offset - 进入数组的偏移量

返回:

从boolean数组加载的掩码

抛出:

IndexOutOfBoundsException - 如果对于矢量掩码中的任何通道N，offset+N < 0或offset+N >= a.length

参见:

• VectorMask.fromArray(VectorSpecies,boolean[],int)

maskAll

             VectorMask<E> maskAll(boolean bit)
            

返回此种类的掩码，其中每个通道根据给定的单个布尔值设置或取消设置，该值广播到所有通道。

参数:

bit - 要复制的给定掩码位

返回:

每个通道根据给定位设置或取消设置的掩码

参见:

• Vector.maskAll(boolean)

broadcast

             Vector<E> broadcast(long e)
            

返回给定种类的矢量，其中所有通道元素都设置为原始值e。

此方法返回以下表达式的值：EVector.broadcast(this, (ETYPE)e)，其中EVector是特定于此种类的ETYPE的矢量类。 long值必须能够准确表示为ETYPE，以便e==(long)(ETYPE)e。

参数:

e - 要广播的值

返回:

所有通道元素都设置为e的矢量

抛出:

IllegalArgumentException - 如果给定的long值不能被矢量种类ETYPE表示

参见:

• Vector.broadcast(long)
• checkValue(long)

checkValue

             long checkValue(long e)
            

检查此种类是否能表示给定的元素值，并返回未更改的值。 long值必须能够准确表示矢量种类的ETYPE，以便e==(long)(ETYPE)e。效果类似于此伪代码：e == (long)(ETYPE)e ? e : throw new IllegalArgumentException()。

参数:

e - 要检查的值

返回:

e

抛出:

IllegalArgumentException - 如果给定的long值不能被矢量种类ETYPE表示

参见:

• broadcast(long)

shuffleFromValues

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

从一系列源索引为此种类创建一个洗牌。

对于每个洗牌通道，其中N是洗牌通道索引，第N个索引值根据种类VLENGTH进行验证，并且（如果无效）部分包装为范围[-VLENGTH..-1]中的异常索引。

参数:

sourceIndexes - 洗牌将从中提取的源索引

返回:

每个通道的源索引设置为给定的int值的洗牌，如果异常则部分包装

抛出:

IndexOutOfBoundsException - 如果sourceIndexes.length != VLENGTH

参见:

• VectorShuffle.fromValues(VectorSpecies,int...)

shuffleFromArray

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

创建此种类的洗牌，从偏移开始的一个int数组。

对于每个洗牌通道，其中N是洗牌通道索引，索引i + N处的数组元素根据种类VLENGTH进行验证，（如果无效）部分包装到范围[-VLENGTH..-1]的异常索引。

参数：

sourceIndexes - 洗牌将从中提取的源索引

offset - 数组中的偏移量

返回：

每个通道的源索引设置为给定的int值的洗牌，如果异常则部分包装

抛出：

IndexOutOfBoundsException - 如果offset < 0，或offset > sourceIndexes.length - VLENGTH

参见：

• VectorShuffle.fromArray(VectorSpecies,int[],int)

shuffleFromOp

             VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn)
            

从应用于范围[0..VLENGTH-1]的连续值创建此种类的洗牌。

对于每个洗牌通道，其中N是洗牌通道索引，第N个索引值根据种类VLENGTH进行验证，（如果无效）部分包装到范围[-VLENGTH..-1]的异常索引。

应注意确保从此方法生成的VectorShuffle值被视为常量，以确保代码的最佳生成。例如，洗牌值可以保存在static final字段或循环不变的局部变量中。

此方法的行为就像从映射索引数组创建洗牌一样：

   int[] a = new int[VLENGTH];
   for (int i = 0; i < a.length; i++) {
       a[i] = fn.applyAsInt(i);
   }
   return VectorShuffle.fromArray(this, a, 0);
 

参数：

fn - 通道索引映射函数

返回：

映射索引的洗牌

参见：

• VectorShuffle.fromOp(VectorSpecies,IntUnaryOperator)

iotaShuffle

             VectorShuffle<E> iotaShuffle(int start, int step, boolean wrap)
            

使用从start开始并按给定step递增的顺序值设置源索引创建洗牌。

此方法返回表达式VectorSpecies.shuffleFromOp(i -> R(start + i * step))的值，其中R是wrapIndex，如果wrap为true，则为wrapIndex，否则为恒等函数。

如果wrap为false，则每个索引根据种类VLENGTH进行验证，（如果无效）部分包装到范围[-VLENGTH..-1]的异常索引。否则，如果wrap为true，则还将每个索引减少，就像通过wrapIndex将其减少到有效范围[0..VLENGTH-1]。

API注释：

如果无效的源索引应该被包装，则wrap参数应设置为true。否则，将其设置为false允许后续操作（如unary rearrange）对无效的源索引进行范围检查。

参数：

start - 源索引序列的起始值，通常为0

step - 相邻源索引之间的差异，通常为1

wrap - 是否将结果索引包装为VLENGTH的模数

返回：

顺序通道索引的洗牌

参见：

• VectorShuffle.iota(VectorSpecies,int,int,boolean)

toString

             String toString()
            

返回形式为"Species[ETYPE, VLENGTH, SHAPE]"的字符串，其中ETYPE是原始通道类型，VLENGTH是与该种类关联的矢量通道计数， SHAPE是与该种类关联的矢量形状。

覆盖：

toString 在类 Object

返回：

形式为"Species[ETYPE, VLENGTH, SHAPE]"的字符串

equals

             boolean equals(Object obj)
            

指示此种类是否与其他某个对象相同。只有当两个种类具有相同的形状和相同的元素类型时，它们才是相同的。

覆盖：

equals 在类 Object

参数：

obj - 要比较的参考对象

返回：

此种类是否与其他某个对象相同

参见：

• Object.hashCode()
• HashMap

hashCode

             int hashCode()
            

为该种类返回基于矢量形状和元素类型的哈希码值。

覆盖：

hashCode 在类 Object

返回：

此种类的哈希码值

参见：

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)