Класс VectorMask<E>

java.lang.Object

jdk.incubator.vector.VectorMask<E>

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

public abstract sealed 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

Модификатор и тип	Метод	Описание
`protected Object`	`clone()`	Создает и возвращает копию этого объекта.
`protected void`	`finalize()`	Устарело, для удаления: этот элемент API подлежит удалению в будущей версии. Финализация объявлена устаревшей и подлежит удалению в будущем выпуске.
`final Class<?>`	`getClass()`	Возвращает класс времени выполнения этого `Object`.
`final void`	`notify()`	Пробуждает один поток, ожидающий на мониторе этого объекта.
`final void`	`notifyAll()`	Пробуждает все потоки, ожидающие на мониторе этого объекта.
`final void`	`wait()`	Заставляет текущий поток ждать пробуждения, обычно посредством уведомления или прерывания.
`final void`	`wait(long timeoutMillis)`	Заставляет текущий поток ждать пробуждения, обычно посредством уведомления или прерывания, либо истечения заданного промежутка реального времени.
`final void`	`wait(long timeoutMillis, int nanos)`	Заставляет текущий поток ждать пробуждения, обычно посредством уведомления или прерывания, либо истечения заданного промежутка реального времени.

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

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).

Эта побитовая бинарная операция проверяет равенство каждой соответствующей пары битов масок. Она также эквивалентна применению логической операции 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 установлен, в результирующий вектор в элемент с индексом N помещается специальное ненулевое значение -1. В противном случае в элемент результирующего вектора с индексом N помещается значение элемента по умолчанию 0. Независимо от того, является ли тип элемента (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.