Класс VectorMask<E>

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 и 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)
 
```

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

Модификатор и тип	Метод	Описание
`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 - вторая входная маска
Возвращает:: результат логического соединения двух входных масок

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 - входная маска
Возвращает:: результат логического исключающего или двух входных масок

END_OF_DOCUMENT_MARKER

andNot

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

Логически вычитает вторую входную маску из этой маски (как a&~b).

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

Parameters:: m - вторая входная маска
Returns:: результат логического вычитания второй маски из этой маски

eq

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

Определяет логическое равенство этой маски и второй входной маски (как булево a==b или a^~b).

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

Parameters:

m - входная маска

Returns:

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

See Also:

not

public abstract VectorMask<E> not()

Логически инвертирует эту маску.

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

Returns:: результат логического отрицания этой маски

indexInRange

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

Удаляет номера линий N из этой маски, где скорректированный индекс N+offset, не находится в диапазоне [0..limit-1].

Во всех случаях серия установленных и не установленных линий назначается так, как если бы использовалась бесконечная точность или VLENGTH- насыщающие сложения или вычитания без переполнения или обхода.

API Note:

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

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

Parameters:

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

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

Returns:

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

See Also:

indexInRange

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

Удаляет номера линий N из этой маски, где скорректированный индекс N+offset, не находится в диапазоне [0..limit-1].

API Note:

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

Parameters:

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

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

Returns:

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

Since:

See Also:

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 Note:

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

Returns:

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

See Also:

laneIsSet

public abstract boolean laneIsSet(int i)

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

Parameters:: i - индекс линии
Returns:: true, если линия с индексом i установлена, в противном случае false
Throws:: IndexOutOfBoundsException - если индекс находится вне диапазона (< 0 || >= length())

check

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

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

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

Type Parameters:

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

Parameters:

elementType - требуемый тип линии

Returns:

та же маска

Throws:

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

See Also:

check

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

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

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

Type Parameters:

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

Parameters:

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

Returns:

та же маска

Throws:

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

See Also:

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:

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

See Also:

hashCode

public final int hashCode()

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

Overrides:

hashCode в классе Object

Returns:

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

See Also:

compress

public abstract VectorMask<E> compress()

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

Возвращает:: сжатую маску этой маски
С:: 19

getPayload

protected final Object getPayload()

© 1993, 2023, 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/21/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorMask.html

Класс VectorMask<E>

Классы со значениями и операции с тождеством

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

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

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

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