Класс VectorMask<E>

java.lang.Object

jdk.incubator.vector.VectorMask<E>

Параметры типа:: E - упакованная версия ETYPE, тип элемента вектора

public abstract class VectorMask<E> extends Object

Объект VectorMask представляет упорядоченную неизменяемую последовательность значений boolean.

VectorMask и Vector с одинаковым типом элемента (ETYPE) и shape имеют одинаковое количество элементов, и, следовательно, совместимы (в частности, их vector species совместимы).

Некоторые векторные операции принимают (совместимые) маски для управления выбором и операцией над элементами столбцов входных векторов.

Количество значений в последовательности называется длиной VectorMask length. Длина также соответствует количеству элементов 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, or 1 for &
 for (int i = 0; i < a.length(); i++) {
      acc = scalar_binary_op(acc, a.laneIsSet(i) ? 1 : 0);  // & | +
 }
 return acc;  // maybe boolean (acc != 0)
 
```

Классы на основе значений и операции с идентичностью

VectorMask, наряду с Vector, является классом на основе значений. С VectorMask, операции, чувствительные к идентичности, такие как ==, могут давать непредсказуемые результаты или снижать производительность. Неожиданно, v.equals(w) может оказаться быстрее, чем v==w, поскольку equals — не чувствительная к идентичности операция. (Так же, как и toString и hashCode). Кроме того, объекты векторной маски могут храниться в локальных переменных и параметрах, а также в качестве static final констант, но хранение их в других полях Java или в элементах массива, хотя и семантически корректно, может повлечь за собой снижение производительности.

Краткое описание методов

Модификатор и тип	Метод	Описание
`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)`	Проверяет, что у этой маски есть данный вид, и возвращает эту маску без изменений.
`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()`	Возвращает значение хэш-кода для маски, основанное на установленных битах маски и виде вектора.
`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()`	Возвращает вид вектора, к которому применима эта маска.
`abstract VectorMask<E>`	`xor(VectorMask<E> m)`	Определяет логическое симметричное различие (как `a^b`) этой маски и второй входной маски.

Методы, объявленные в классе java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Подробное описание методов

vectorSpecies

public abstract VectorSpecies<E> vectorSpecies()

Возвращает вид вектора, к которому применяется эта маска. Эта маска применяется к векторам того же вида и того же количества элементов.

Возвращает:: вид вектора этой маски

length

public final int length()

Возвращает количество элементов маски. Эта маска применяется к векторам с тем же количеством элементов и тем же видом.

Возвращает:: количество элементов маски

fromValues

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

Возвращает маску, где каждый элемент устанавливается или сбрасывается в соответствии с заданными boolean значениями.

Для каждого элемента маски, где N — индекс элемента маски, если заданное boolean значение по индексу N равно true, то элемент маски по индексу N устанавливается, в противном случае — сбрасывается.

Заданный вид должен иметь количество элементов, совместимое с заданным массивом.

Тип параметров:

E - упакованный тип элемента

Параметры:

species - вид вектора для желаемой маски

bits - заданные boolean значения

Возвращает:

маску, где каждый элемент устанавливается или сбрасывается в соответствии с заданным boolean значением

Исключения:

IllegalArgumentException - если bits.length != species.length()

См. также:

fromArray

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

Загружает маску из массива boolean, начиная со смещения.

Для каждого элемента маски, где N — индекс элемента маски, если элемент массива по индексу offset + N равен true, то элемент маски по индексу N устанавливается, в противном случае — сбрасывается.

Тип параметров:

E - упакованный тип элемента

Параметры:

species - вид вектора для желаемой маски

bits - массив boolean

offset - смещение в массиве

Возвращает:

маску, загруженную из массива boolean

Исключения:

IndexOutOfBoundsException - если offset < 0 или offset > bits.length - species.length()

См. также:

fromLong

public static <E> VectorMask<E> fromLong(VectorSpecies<E> species, long bits)

Возвращает маску, где каждый элемент устанавливается или сбрасывается в соответствии с битами в заданной битовой маске, начиная с младшего бита и продолжая до знакового бита.

Для каждого элемента маски, где N — индекс элемента маски, если выражение (bits>>min(63,N))&1 не равно нулю, то элемент маски по индексу N устанавливается, в противном случае — сбрасывается.

Если у заданного вида меньше 64 элементов, старшие 64-VLENGTH биты битовой маски игнорируются. Если у заданного вида больше 64 элементов, знаковый бит дублируется для элементов с индексами 64 и далее.

Тип параметров:

E - упакованный тип элемента

Параметры:

species - вид вектора для желаемой маски

bits - заданные биты маски как 64-битовое целое со знаком

Возвращает:

маску, где каждый элемент устанавливается или сбрасывается в соответствии с битами в заданном целочисленном значении

См. также:

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 — индекс элемента маски, если элемент маски установлен, то N-й бит в результирующем значении long устанавливается в единицу, в противном случае 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 - вторая входная маска
Возвращает:: результат логического конъюнкта двух входных масок

или

public abstract VectorMask<E> or(VectorMask<E> m)

Вычисляет логическое объединение (как a|b) этой маски и второй входной маски.

Это бинарная операция по каждой дорожке, которая применяет логическую операцию OR (|) к каждой соответствующей паре битов маски.

Параметры:: m - входная маска
Возвращает:: результат логического объединения двух входных масок

искл. или

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 - входная маска

Возвращает:

маска, показывающая, где две входные маски были равны

См. также:

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:

Этот метод выполняет эмуляцию SIMD проверки, выполняемой Objects.checkIndex(int,int), по индексам в диапазоне [offset..offset+VLENGTH-1]. Если требуется исключение, результирующая маска может быть сравнена с исходной маской; если они не равны, то хотя бы одна дорожка была вне диапазона, и можно выполнить обработку исключения.

Маска, которая представляет собой последовательность N установленных дорожек, за которой следуют последовательность сброшенных дорожек, может быть получена вызовом allTrue.indexInRange(0, N), где allTrue - маска всех установленных битов. Маска из N1 сброшенных дорожек, за которой следуют N2 установленных дорожек, может быть получена вызовом allTrue.indexInRange(-N1, N2).

Параметры:

offset - начальный индекс

limit - верхняя граница (исключая) диапазона индексов

Возвращает:

исходная маска с дорожками вне диапазона, сброшенными

См. также:

indexInRange

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

Примечание API:

Этот метод выполняет эмуляцию SIMD проверки, выполняемой Objects.checkIndex(long,long), по индексам в диапазоне [offset..offset+VLENGTH-1]. Если требуется исключение, результирующая маска может быть сравнена с исходной маской; если они не равны, то хотя бы одна дорожка была вне диапазона, и можно выполнить обработку исключения.

Параметры:

offset - начальный индекс

limit - верхняя граница (исключая) диапазона индексов

Возвращает:

исходная маска с дорожками вне диапазона, сброшенными

С:

См. также:

toVector

public abstract Vector<E> toVector()

Возвращает векторное представление этой маски, биты дорожек которой установлены или сброшены в соответствии с битами маски. Для каждой дорожки маски, где N - индекс дорожки маски, если дорожка маски установлена в N, то определённое ненулевое значение -1 помещается в результирующий вектор на индексе дорожки N. В противном случае значение по умолчанию 0 помещается в результирующий вектор на индексе дорожки N. Будь то тип элемента (ETYPE) этой маски с плавающей запятой или целого типа, значение дорожки, как выбрано маской, будет одним из двух арифметических значений 0 или -1. Для каждой ETYPE самый старший бит дорожки вектора установлен тогда и только тогда, когда дорожка маски установлена. Кроме того, для целочисленных типов все биты дорожки установлены в дорожках, где маска установлена.

Возвращаемый вектор такой же, как если бы он был вычислен с помощью ZERO.blend(MINUS_ONE, this), где ZERO и MINUS_ONE являются векторами, которые дублируют значение по умолчанию ETYPE и значение ETYPE, представляющее -1, соответственно.

Примечание API:

Для целей статической проверки типов пользователи могут захотеть проверить результирующий вектор по ожидаемому целочисленному типу дорожки или спецификации. Если маска предназначена для спецификации с плавающей запятой, то результирующий вектор будет иметь ту же форму и размер дорожки, но целочисленный тип. Если маска предназначена для целочисленной спецификации, результирующий вектор будет иметь именно эту спецификацию.

Возвращает:

векторное представление этой маски

См. также:

laneIsSet

public abstract boolean laneIsSet(int i)

Проверяет, установлена ли дорожка с индексом i

Параметры:: i - индекс дорожки
Возвращает:: true, если дорожка с индексом i установлена, иначе false
Исключения:: IndexOutOfBoundsException - если индекс вне диапазона (< 0 || >= length())

check

public abstract <F> VectorMask<F> check(Class<F> elementType)

Проверяет, что эта маска применима к векторам с заданным типом элемента и возвращает эту маску без изменений. Эффект аналогичен этому псевдокоду:

elementType == vectorSpecies().elementType()
        ? this
        : throw new ClassCastException()

Параметры типа:

F - упакованный тип элемента требуемого типа дорожки

Параметры:

elementType - требуемый тип дорожки

Возвращает:

такую же маску

Исключения:

ClassCastException - если тип элемента неверный

См. также:

check

public abstract <F> VectorMask<F> check(VectorSpecies<F> species)

Проверяет, что эта маска имеет заданную спецификацию, и возвращает эту маску без изменений. Эффект аналогичен этому псевдокоду:

species == vectorSpecies()
        ? this
        : throw new ClassCastException()

Параметры типа:

F - упакованный тип элемента требуемой спецификации

Параметры:

species - требуется векторная спецификация для этой маски

Возвращает:

ту же самую маску

Исключения:

ClassCastException - если спецификация неверная

См. также:

toString

public final String toString()

Возвращает строковое представление этой маски в формате "Mask[T.TT...]", отображая установки битов маски (как символы 'T' или '.') в порядке элементов.

Overrides:: toString в классе Object
Returns:: строка формата "Mask[T.TT...]"

equals

public final boolean equals(Object obj)

Указывает, идентична ли эта маска какому-либо другому объекту. Две маски идентичны только в том случае, если у них одинаковые типы и одинаковые индексы источника в одинаковом порядке.

Overrides:

equals в классе Object

Parameters:

obj - объект-ссылка для сравнения.

Returns:

является ли этот вектор идентичным какому-либо другому объекту

См. также:

hashCode

public final int hashCode()

Возвращает значение хэш-кода для маски, основанное на установках битов маски и типе вектора.

Overrides:

hashCode в классе Object

Returns:

значение хэш-кода для этой маски

См. также:

compress

public abstract VectorMask<E> compress()

Сжимает установленные элементы из этой маски. Возвращает маску, которая представляет собой серию N установленных элементов, за которой следует серия сброшенных элементов, где N — истинное количество этой маски.

Returns:: сжатая маска этой маски
Since:: 19

getPayload

protected final Object getPayload()

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorMask.html