Класс 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`) этой маски и второй входной маски.

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

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 типа boolean).

Эта бинарная поэлементная операция проверяет равенство каждой соответствующей пары битов масок. Она также эквивалентна применению логической операции 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' или '.') в порядке дорожек.

Переопределяет:: toString в классе Object
Возвращает:: строку в форме "Mask[T.TT...]"

equals

public final boolean equals(Object obj)

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

Переопределяет:

equals в классе Object

Параметры:

obj — объект-ссылка, с которым выполняется сравнение.

Возвращает:

указывает, идентичен ли этот вектор другому объекту

См. также:

hashCode

public final int hashCode()

Возвращает хеш-код маски, основанный на состояниях битов маски и виде вектора.

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этой маски

См. также:

compress

public abstract VectorMask<E> compress()

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

Возвращает:: сжатую маску, полученную из этой маски
С версии:: 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://docs.oracle.com/en/java/javase/25/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorMask.html