java.lang.Object

jdk.incubator.vector.VectorMask<E>

类型参数:: E - ETYPE的装箱版本，向量的元素类型
基于值的类和标识操作
VectorMask，以及Vector，是一个基于值的类。使用VectorMask时，诸如==的标识敏感操作可能会产生不可预测的结果，或者降低性能。奇怪的是，v.equals(w)可能比v==w更快，因为equals不是一个标识敏感的方法（toString和hashCode也不是）。此外，向量掩码对象可以存储在局部变量和参数中，也可以作为static final常量存储，但将它们存储在其他Java字段或数组元素中，虽然在语义上是有效的，但可能会导致性能损失。

public abstract class VectorMask<E> extends Object

VectorMask表示一个有序的不可变的boolean值序列。

VectorMask和具有相同元素类型（ETYPE）和shape的Vector具有相同数量的通道，因此它们是兼容的（具体来说，它们的vector species是兼容的）。

一些向量操作接受（兼容的）掩码来控制输入向量的通道元素的选择和操作。

序列中的值的数量称为VectorMask的长度。长度也对应于VectorMask通道的数量。通道索引为N（从0（包括）到长度（不包括））的通道元素对应于序列中的第N + 1个值。

如果通道元素为true，则通道被称为设置，否则如果通道元素为false，则通道被称为未设置。

VectorMask声明了一组有限的一元、二元和归约操作。

一元逐通道操作对一个输入掩码进行操作并生成一个结果掩码。对于输入掩码的每个通道，使用指定的标量一元操作对通道元素进行操作，并将布尔结果放入相同通道的结果掩码中。以下伪代码说明了此操作类别的行为：
```
 VectorMask<E> a = ...;
 boolean[] ar = new boolean[a.length()];
 for (int i = 0; i < a.length(); i++) {
     ar[i] = scalar_unary_op(a.laneIsSet(i));
 }
 VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);
 
```
二元逐通道操作对两个输入掩码进行操作以生成一个结果掩码。对于两个输入掩码a和b的每个通道，使用指定的标量二元操作对a和b的相应通道元素进行操作，并将布尔结果放入相同通道的结果掩码中。以下伪代码说明了此操作类别的行为：
```
 VectorMask<E> a = ...;
 VectorMask<E> b = ...;
 boolean[] ar = new boolean[a.length()];
 for (int i = 0; i < a.length(); i++) {
     ar[i] = scalar_binary_op(a.laneIsSet(i), b.laneIsSet(i));
 }
 VectorMask<E> r = VectorMask.fromArray(a.vectorSpecies(), ar, 0);
 
```
交叉通道归约操作接受一个输入掩码并生成一个标量结果。对于输入掩码的每个通道，使用指定的标量二元操作对通道元素进行操作，以及一个标量累加值。标量结果是累加器的最终值。以下伪代码说明了此操作类别的行为：
```
 Mask<E> a = ...;
 int acc = zero_for_scalar_binary_op;  // 0，或者1用于&
 for (int i = 0; i < a.length(); i++) {
      acc = scalar_binary_op(acc, a.laneIsSet(i) ? 1 : 0);  // & | +
 }
 return acc;  // 可能是布尔值（acc != 0）
 
```

Method Summary

Modifier and Type

Method

Description

abstract boolean

allTrue()

如果所有掩码通道都设置，则返回true。

abstract VectorMask<E>

and(VectorMask<E> m)

计算此掩码与第二个输入掩码的逻辑交集（如a&b）。

abstract VectorMask<E>

andNot(VectorMask<E> m)

从此掩码中逻辑减去第二个输入掩码（如a&~b）。

abstract boolean

anyTrue()

如果任何掩码通道都设置，则返回true。

abstract <F> VectorMask<F>

cast(VectorSpecies<F> species)

将此掩码转换为给定元素类型F的掩码。

abstract <F> VectorMask<F>

check(Class<F> elementType)

检查此掩码适用于具有给定元素类型的向量，并返回此掩码不变。

abstract <F> VectorMask<F>

check(VectorSpecies<F> species)

检查此掩码具有给定species，并返回此掩码不变。

abstract VectorMask<E>

compress()

从此掩码中压缩设置的通道。

abstract VectorMask<E>

eq(VectorMask<E> m)

确定此掩码与第二个输入掩码的逻辑等价性（如布尔a==b或a^~b）。

final boolean

equals(Object obj)

指示此掩码是否与其他对象相同。

abstract int

firstTrue()

返回第一个设置的掩码通道的索引。

static <E> VectorMask<E>

fromArray(VectorSpecies<E> species, boolean[] bits, int offset)

从偏移量开始从boolean数组加载掩码。

static <E> VectorMask<E>

fromLong(VectorSpecies<E> species, long bits)

返回一个掩码，其中每个通道根据给定位掩中的位设置或未设置，从最低有效位开始，一直到符号位。

static <E> VectorMask<E>

fromValues(VectorSpecies<E> species, boolean... bits)

返回一个掩码，其中每个通道根据给定boolean值设置或未设置。

protected final Object

getPayload()

final int

hashCode()

返回掩码的哈希码值，基于掩码位设置和向量species。

abstract VectorMask<E>

indexInRange(int offset, int limit)

从此掩码中删除通道编号为N的通道，其中调整后的索引N+offset不在范围[0..limit-1]内。

abstract VectorMask<E>

indexInRange(long offset, long limit)

从此掩码中删除通道编号为N的通道，其中调整后的索引N+offset不在范围[0..limit-1]内。

abstract void

intoArray(boolean[] a, int offset)

将此掩码存储到从偏移量开始的boolean数组中。

abstract boolean

laneIsSet(int i)

测试索引为i的通道是否设置。

abstract int

lastTrue()

返回最后一个设置的掩码通道的索引。

final int

length()

返回掩码通道的数量。

abstract VectorMask<E>

not()

逻辑否定此掩码。

abstract VectorMask<E>

or(VectorMask<E> m)

计算此掩码与第二个输入掩码的逻辑并集（如a|b）。

abstract boolean[]

toArray()

返回包含此掩码通道元素的boolean数组。

abstract long

toLong()

返回此掩码的通道元素打包成long值，最多为前64个通道元素。

final String

toString()

返回此掩码的字符串表示形式，形式为"Mask[T.TT...]"，按通道顺序报告掩码位设置（作为'T'或'.'字符）。

abstract Vector<E>

toVector()

返回此掩码的向量表示，其中通道位根据掩码位设置或未设置。

abstract int

trueCount()

返回设置的掩码通道的数量。

abstract VectorSpecies<E>

vectorSpecies()

返回此掩码适用的向量species。

abstract VectorMask<E>

xor(VectorMask<E> m)

计算此掩码与第二个输入掩码的逻辑对称差（如a^b）。

Methods declared in class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Method Details
- vectorSpecies
  
  public abstract VectorSpecies<E> vectorSpecies()
  
  返回此掩码适用的向量species。此掩码适用于具有相同species和相同通道数量的向量。
  
  返回:
  
  此掩码的vector species
- length
  
  public final int length()
  
  返回掩码通道的数量。此掩码适用于具有相同通道数量和相同species的向量。
  
  返回:
  
  掩码通道的数量
- fromValues
  
  public static <E> VectorMask<E> fromValues(VectorSpecies<E> species, boolean... bits)
  
  返回一个掩码，其中每个通道根据给定boolean值设置或未设置。
  对于每个掩码通道，其中N是掩码通道索引，如果索引N处的给定boolean值为true，则索引N处的掩码通道被设置，否则未设置。
  
  给定的species必须具有与给定数组兼容的通道数量。
  类型参数:
  
  E - 装箱元素类型
  
  参数:
  
  species - 所需掩码的向量species
  
  bits - 给定的boolean值
  
  返回:
  
  每个通道根据给定boolean值设置或未设置的掩码
  
  抛出:
  
  IllegalArgumentException - 如果bits.length != species.length()
  
  参见:
  
  fromLong(VectorSpecies, long)
  
  fromArray(VectorSpecies, boolean[], int)
- fromArray
  
  public static <E> VectorMask<E> fromArray(VectorSpecies<E> species, boolean[] bits, int offset)
  
  从偏移量开始从boolean数组加载掩码。
  对于每个掩码通道，其中N是掩码通道索引，如果数组中索引offset + N处的元素为true，则索引N处的掩码通道被设置，否则未设置。
  类型参数:
  
  E - 装箱元素类型
  
  参数:
  
  species - 所需掩码的向量species
  
  bits - boolean数组
  
  offset - 数组中的偏移量
  
  返回:
  
  从boolean数组加载的掩码
  
  抛出:
  
  IndexOutOfBoundsException - 如果offset < 0，或者offset > bits.length - species.length()
  
  参见:
  
  fromLong(VectorSpecies, long)
  
  fromValues(VectorSpecies, boolean...)
- fromLong
  
  public static <E> VectorMask<E> fromLong(VectorSpecies<E> species, long bits)
  
  返回一个掩码，其中每个通道根据给定位掩中的位设置或未设置，从最低有效位开始，一直到符号位。
  对于每个掩码通道，其中N是掩码通道索引，如果表达式(bits>>min(63,N))&1非零，则索引N处的掩码通道被设置，否则未设置。
  
  如果给定的species少于64个通道，位掩的高64-VLENGTH位将被忽略。如果给定的species多于64个通道，则符号位将复制到第64个通道及更高通道。
  类型参数:
  
  E - 包装的元素类型
  
  参数:
  
  species - 所需掩码的向量种类
  
  bits - 给定的掩码位，作为64位有符号整数
  
  返回:
  
  每个通道根据给定整数值中的位设置或取消的掩码
  
  参见:
  
  fromValues(VectorSpecies, boolean...)
  
  fromArray(VectorSpecies, boolean[], int)
- cast
  
  public abstract <F> VectorMask<F> cast(VectorSpecies<F> species)
  
  将此掩码转换为给定元素类型F的掩码。 species.length()必须等于掩码长度。各种掩码通道位不变。
  对于每个掩码通道，其中N是通道索引，如果索引为N的掩码通道已设置，则结果掩码的索引为N的掩码通道也已设置，否则该掩码通道未设置。
  
  类型参数:
  
  F - 种类的包装元素类型
  
  参数:
  
  species - 所需掩码的向量种类
  
  返回:
  
  通过形状和元素类型转换的掩码
  
  抛出:
  
  IllegalArgumentException - 如果此掩码长度与种类长度不同
- toLong
  
  public abstract long toLong()
  
  返回将此掩码打包为long值的通道元素，最多为前64个通道元素。
  通道元素按从最低有效位到最高有效位的顺序打包。对于每个掩码通道，其中N是掩码通道索引，如果掩码通道已设置，则结果long值中的第N位设置为一，否则第N位设置为零。掩码不能超过64个通道。
  
  返回:
  
  将此掩码打包为long值的通道元素。
  
  抛出:
  
  UnsupportedOperationException - 如果此掩码中有超过64个通道
- toArray
  
  public abstract boolean[] toArray()
  返回包含此掩码通道元素的boolean数组。
  此方法的行为就好像将此掩码存储到分配的数组中（使用intoArray(boolean[], int)），并将该数组返回如下：
  
  boolean[] a = new boolean[this.length()]; this.intoArray(a, 0); return a;
  返回:
  
  包含此向量通道元素的数组
- intoArray
  
  public abstract void intoArray(boolean[] a, int offset)
  
  将此掩码存储到从偏移量开始的boolean数组中。
  对于每个掩码通道，其中N是掩码通道索引，将索引为N的通道元素存储到数组元素a[offset+N]中。
  
  参数:
  
  a - 数组，类型为boolean[]
  
  offset - 数组中的偏移量
  
  抛出:
  
  IndexOutOfBoundsException - 如果offset < 0或offset > a.length - this.length()
- anyTrue
  
  public abstract boolean anyTrue()
  
  如果任何掩码通道已设置，则返回true。
  
  返回:
  
  如果任何掩码通道已设置，则返回true，否则返回false。
- allTrue
  
  public abstract boolean allTrue()
  
  如果所有掩码通道都已设置，则返回true。
  
  返回:
  
  如果所有掩码通道都已设置，则返回true，否则返回false。
- trueCount
  
  public abstract int trueCount()
  
  返回已设置的掩码通道数。
  
  返回:
  
  已设置的掩码通道数。
- firstTrue
  
  public abstract int firstTrue()
  
  返回第一个已设置的掩码通道的索引。如果没有设置任何通道，则返回VLENGTH。
  
  返回:
  
  第一个已设置的掩码通道的索引，或VLENGTH
- lastTrue
  
  public abstract int lastTrue()
  
  返回最后一个已设置的掩码通道的索引。如果没有设置任何通道，则返回-1。
  
  返回:
  
  最后一个已设置的掩码通道的索引，或-1
- and
  
  public abstract VectorMask<E> and(VectorMask<E> m)
  
  计算此掩码与第二个输入掩码之间的逻辑交集（作为a&b）。
  这是一种逐通道二进制操作，对每对对应的掩码位应用逻辑AND操作（&）。
  
  参数:
  
  m - 第二个输入掩码
  
  返回:
  
  逻辑上连接两个输入掩码的结果
- or
  
  public abstract VectorMask<E> or(VectorMask<E> m)
  
  计算此掩码与第二个输入掩码的逻辑并集（作为a|b）。
  这是一种逐通道二进制操作，对每对对应的掩码位应用逻辑OR操作（|）。
  
  参数:
  
  m - 输入掩码
  
  返回:
  
  逻辑上连接两个输入掩码的结果
- xor
  
  public abstract VectorMask<E> xor(VectorMask<E> m)
  
  确定此掩码与第二个输入掩码的逻辑对称差（作为a^b）。
  这是一种逐通道二进制操作，对每对对应的掩码位应用逻辑XOR操作（^）。
  
  参数:
  
  m - 输入掩码
  
  返回:
  
  逻辑上连接两个输入掩码的结果
- andNot
  
  public abstract VectorMask<E> andNot(VectorMask<E> m)
  
  从此掩码中逻辑减去第二个输入掩码（作为a&~b）。
  这是一种逐通道二进制操作，对每对对应的掩码位应用逻辑ANDC操作（&~）。
  
  参数:
  
  m - 第二个输入掩码
  
  返回:
  
  逻辑上从此掩码中减去第二个掩码的结果
- eq
  
  public abstract VectorMask<E> eq(VectorMask<E> m)
  
  确定此掩码与第二个输入掩码的逻辑等价性（作为布尔a==b或a^~b）。
  这是一种逐通道二进制操作，测试每对对应的掩码位是否相等。它还等同于对每对对应的掩码位应用逻辑XNOR操作（^~）。
  参数:
  
  m - 输入掩码
  
  返回:
  
  显示两个输入掩码相等的掩码
  
  参见:
  
  equals(java.lang.Object)
- not
  
  public abstract VectorMask<E> not()
  
  对此掩码进行逻辑否定。
  这是一种逐通道二进制操作，对每个掩码位应用逻辑NOT操作（~）。
  
  返回:
  
  逻辑否定此掩码的结果
- indexInRange
  
  public abstract VectorMask<E> indexInRange(int offset, int limit)
  
  从此掩码中删除编号为N的通道，其中调整后的索引N+offset不在范围[0..limit-1]内。
  在所有情况下，设置和未设置通道的系列都被分配，就好像使用无限精度或VLENGTH-饱和加法或减法，没有溢出或环绕。
  API注释:
  
  此方法对范围[offset..offset+VLENGTH-1]中的索引号执行类似于Objects.checkIndex(int,int)的检查的SIMD模拟。如果需要异常，可以将结果掩码与原始掩码进行比较；如果它们不相等，则至少有一个通道超出范围，可以执行异常处理。
  可以通过调用allTrue.indexInRange(0, N)获得一系列N设置通道后跟一系列未设置通道的掩码，其中allTrue是所有真位的掩码。可以通过调用allTrue.indexInRange(-N1, N2)获得一系列N1未设置通道后跟N2设置通道的掩码。
  
  参数:
  
  offset - 起始索引
  
  limit - 索引范围的上限（不包括）
  
  返回:
  
  原始掩码，超出范围的通道未设置
  
  参见:
  
  VectorSpecies.indexInRange(int, int)
- indexInRange
  
  public abstract VectorMask<E> indexInRange(long offset, long limit)
  
  从此掩码中删除编号为N的通道，其中调整后的索引N+offset不在范围[0..limit-1]内。
  在所有情况下，设置和未设置通道的系列都被分配，就好像使用无限精度或VLENGTH-饱和加法或减法，没有溢出或环绕。
  API注释:
  
  此方法对范围[offset..offset+VLENGTH-1]中的索引号执行类似于Objects.checkIndex(long,long)的检查的SIMD模拟。如果需要异常，可以将结果掩码与原始掩码进行比较；如果它们不相等，则至少有一个通道超出范围，可以执行异常处理。
  可以通过调用allTrue.indexInRange(0, N)获得一系列N设置通道后跟一系列未设置通道的掩码，其中allTrue是所有真位的掩码。可以通过调用allTrue.indexInRange(-N1, N2)获得一系列N1未设置通道后跟N2设置通道的掩码。
  
  参数:
  
  offset - 起始索引
  
  limit - 索引范围的上限（不包括）
  
  返回:
  
  原始掩码，超出范围的通道未设置
  
  自:
  
  19
  
  参见:
  
  VectorSpecies.indexInRange(long, long)
- toVector
  
  public abstract Vector<E> toVector()
  
  返回此掩码的向量表示，其中的通道位设置或取消，与掩码位对应。对于每个掩码通道，其中N是掩码通道索引，如果在N处设置了掩码通道，则在结果向量的N处放入特定的非默认值-1。否则，在结果向量的N处放入默认元素值0。无论此掩码的元素类型（ETYPE）是浮点还是整数，由掩码选择的通道值将是两个算术值0或-1中的一个。对于每个ETYPE，只有当掩码通道被设置时，向量通道的最高有效位才会被设置。此外，对于整数类型，在掩码被设置的通道中，所有通道位都被设置。
  返回的向量与通过ZERO.blend(MINUS_ONE, this)计算的向量相同，其中ZERO和MINUS_ONE是分别复制默认ETYPE值和表示-1的ETYPE值的向量。
  API 注意：
  
  为了进行静态类型检查，用户可能希望将生成的向量与预期的整数通道类型或种类进行检查。如果掩码是针对浮点种类的，则生成的向量将具有相同的形状和通道大小，但是整数类型。如果掩码是针对整数种类的，则生成的向量将完全是该种类的。
  
  返回：
  
  此掩码的向量表示
  
  另请参见：
  
  Vector.check(Class)
  
  Vector.check(VectorSpecies)
- laneIsSet
  
  public abstract boolean laneIsSet(int i)
  
  测试索引为i的通道是否被设置
  
  参数：
  
  i - 通道索引
  
  返回：
  
  如果索引为i的通道被设置，则返回true，否则返回false
  
  抛出：
  
  IndexOutOfBoundsException - 如果索引超出范围（< 0 || >= length()）
- check
  
  public abstract <F> VectorMask<F> check(Class<F> elementType)
  
  检查此掩码是否适用于具有给定元素类型的向量，并返回此掩码不变。效果类似于此伪代码：elementType == vectorSpecies().elementType() ? this : throw new ClassCastException()。
  类型参数：
  
  F - 所需通道类型的装箱元素类型
  
  参数：
  
  elementType - 所需通道类型
  
  返回：
  
  相同的掩码
  
  抛出：
  
  ClassCastException - 如果元素类型错误
  
  另请参见：
  
  Vector.check(Class)
  
  check(VectorSpecies)
- check
  
  public abstract <F> VectorMask<F> check(VectorSpecies<F> species)
  
  检查此掩码是否具有给定种类，并返回此掩码不变。效果类似于此伪代码：species == vectorSpecies() ? this : throw new ClassCastException()。
  类型参数：
  
  F - 所需种类的装箱元素类型
  
  参数：
  
  species - 此掩码所需的向量种类
  
  返回：
  
  相同的掩码
  
  抛出：
  
  ClassCastException - 如果种类错误
  
  另请参见：
  
  Vector.check(Class)
  
  Vector.check(VectorSpecies)
- toString
  
  public final String toString()
  
  返回此掩码的字符串表示形式，格式为"Mask[T.TT...]"，报告通道顺序中的掩码位设置（作为'T'或'.'字符）。
  
  覆盖：
  
  toString 在类 Object
  
  返回：
  
  格式为"Mask[T.TT...]"的字符串
- equals
  
  public final boolean equals(Object obj)
  
  指示此掩码是否与其他对象相同。仅当两个掩码具有相同的种类和相同的源索引，且顺序相同时，它们才是相同的。
  覆盖：
  
  equals 在类 Object
  
  参数：
  
  obj - 用于比较的参考对象
  
  返回：
  
  此向量是否与其他对象相同
  
  另请参见：
  
  eq(jdk.incubator.vector.VectorMask<E>)
- hashCode
  
  public final int hashCode()
  
  为掩码基于掩码位设置和向量种类返回哈希码值。
  覆盖：
  
  hashCode 在类 Object
  
  返回：
  
  此掩码的哈希码值
  
  另请参见：
  
  Object.equals(java.lang.Object)
  
  System.identityHashCode(java.lang.Object)
- compress
  
  public abstract VectorMask<E> compress()
  
  从此掩码中压缩设置的通道。返回一个掩码，其中是一系列N个设置的通道，后跟一系列未设置的通道，其中N是此掩码的真实计数。
  
  返回：
  
  此掩码的压缩掩码
  
  自：
  
  19
- getPayload
  
  protected final Object getPayload()

Class VectorMask<E>

基于值的类和标识操作

Method Summary

Methods declared in class java.lang.Object

Method Details

vectorSpecies

length

fromValues

fromArray

fromLong

cast

toLong

toArray

intoArray

anyTrue

allTrue

trueCount

firstTrue

lastTrue

and

or

xor

andNot

eq

not

indexInRange

indexInRange

toVector

laneIsSet

check

check

toString

equals

hashCode

compress

getPayload