模块 jdk.incubator.vector

包 jdk.incubator.vector

接口 VectorSpecies<E>

类型参数：

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

public interface VectorSpecies<E>
      

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

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

程序只能在启用预览功能时使用 VectorSpecies。

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

用于管理 元素类型 (ETYPE ) 和 shape 相同组合的所有向量的接口。

API 注意：

用户代码不应实现此接口。这种类型的未来版本可能会将实现限制为同一包的成员。

实现注意事项：

此接口实例的字符串表示形式为“Species[ETYPE, VLENGTH, SHAPE]”，其中 ETYPE 是原语 车道类型 ，VLENGTH 是与物种相关的 矢量车道数，SHAPE 是与物种相关的 矢量形状 .

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

方法总结

修饰符和类型	方法	描述
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)	从 内存段 加载该物种的向量PREVIEW 从内存段的偏移量开始。
int	hashCode()	根据矢量形状和元素类型返回物种的哈希码值。
VectorMask<E>	indexInRange(int offset, int limit)	返回该物种的掩码，其中仅设置索引 N 处的车道，以便调整后的索引 N+offset 在范围 [0..limit-1] 中。
VectorMask<E>	indexInRange(long offset, long limit)	返回该物种的掩码，其中仅设置索引 N 处的车道，以便调整后的索引 N+offset 在范围 [0..limit-1] 中。
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)	返回该物种的掩码，其中根据给定的单个boolean设置或取消设置每条车道，该boolean广播到所有车道。
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)	给定这个物种和第二个物种，报告一个（可能）调整 重新诠释 或 lane-wise conversion 从这个物种到第二个物种的净膨胀或收缩。
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)	查找具有给定形状和与该物种相同的 elementType 的物种。
Vector<E>	zero()	返回该物种的向量，其中所有车道元素都设置为默认原始值 (ETYPE)0 。

方法详情

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)
            

给定这个物种和第二个物种，报告一个（可能）调整 重新诠释 或 lane-wise conversion 从这个物种到第二个物种的净膨胀或收缩。返回值的符号和大小取决于建议的输入和输出 shapes 之间的大小差异，并且（可选地，如果 lanewise 为真）还取决于建议的输入和输出 lanes 之间的大小差异。

• 首先，确定逻辑结果大小。如果 lanewise 为假，则此大小为输入 VSHAPE 的大小。如果 lanewise 为真，则逻辑结果大小是输入 VLENGTH 乘以 output ETYPE 大小的乘积。
• 接下来，将逻辑结果大小与建议的输出形状的大小进行比较，以查看它如何适合。
• 如果逻辑结果恰好符合输出形状，则返回值为零，表示没有净膨胀或收缩。
• 如果逻辑结果会溢出输出形状，则返回值是逻辑结果大小与（较小的）输出大小的比率（大于一）。该比率可以被视为测量“丢弃的输入位”的比例，必须从输入中删除这些位才能使结果适合输出向量。它也是 part limit ，是将输入物种转换为输出物种的方法的 part 参数的上限。
• 如果逻辑结果将落入输出形状并有剩余空间，则返回值是一个负数，其绝对值是输出大小与（较小的）逻辑结果大小之间的比率（大于一）。该比率可以被视为测量必须添加到逻辑结果以填充输出向量的“额外填充位”的比例。它也是 part limit ，是将输入物种转换为输出物种的方法的 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)
            

查找具有给定形状和与该物种相同的 elementType 的物种。返回与 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 - 如果 offset+N < 0 或 offset+N >= a.length 用于向量中的任何通道 N

参见：

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

fromMemorySegment

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

从 内存段 加载该物种的向量^PREVIEW 从内存段的偏移量开始。字节根据指定的字节顺序组成原始通道元素。矢量根据 内存排序 排列成通道。

相当于 IntVector.fromMemorySegment(this,ms,offset,bo) ，在对应于该物种的向量类型上。

参数：

ms - 内存段

offset - 内存段的偏移量

bo - 预期的字节顺序

返回：

从内存段填充的给定物种的向量

抛出：

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

自从：

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 - 如果 offset+N < 0 或 offset+N >= a.length 用于向量掩码中的任何通道 N

参见：

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

maskAll

VectorMask <E > maskAll(boolean bit)
            

返回该物种的掩码，其中根据给定的单个boolean设置或取消设置每条车道，该boolean广播到所有车道。

参数：

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 值不能由向量 species 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 值不能由向量 species 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)) 的值，其中如果 wrap 为真，则 R 为 wrapIndex ，否则为恒等函数。

如果 wrap 为假，则每个索引都针对物种 VLENGTH 进行验证，并且（如果无效）部分包装到 [-VLENGTH..-1] 范围内的异常索引。否则，如果 wrap 为真，也将每个索引减少到有效范围 [0..VLENGTH-1] ，就像减少 wrapIndex 一样。

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)