Класс VectorShuffle<E>

java.lang.Object

jdk.internal.vm.vector.VectorSupport.VectorPayload

jdk.internal.vm.vector.VectorSupport.VectorShuffle<E>

jdk.incubator.vector.VectorShuffle<E>

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

public abstract class VectorShuffle<E> extends jdk.internal.vm.vector.VectorSupport.VectorShuffle<E>

A VectorShuffle представляет упорядоченную неизменяемую последовательность значений int , называемых индексами источника, где каждый индекс источника численно выбирает целевой канал из совместимого Vector.

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

Перестановка применяется к (совместимому) вектору-источнику с помощью метода rearrange.

Перестановка имеет структуру каналов, полученную из ее вида вектора, но она хранит индексы каналов, как int , а не значения каналов.

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

Каждая перестановка имеет свойство vectorSpecies(), которое определяет совместимость векторов, с которыми работает перестановка. Это гарантирует, что length() перестановки всегда равен VLENGTH любого вектора, с которым она работает. Тип элемента и форма вида перестановки не имеют прямого отношения к поведению перестановки. Перестановки легко можно преобразовать в другие типы каналов, при условии, что количество каналов остается постоянным.

Во внутреннем состоянии перестановка всегда содержит целые значения в узком диапазоне от [-VLENGTH..VLENGTH-1]. Положительные числа понятны сами по себе; это номера каналов, применяемые к любому вектору-источнику. Отрицательные числа, если они присутствуют, указывают на то, что перестановка была создана из целого значения, которое не являлось допустимым индексом канала.

Недопустимый индекс источника, представленный в перестановке отрицательным числом, называется исключительным индексом.

Исключительные индексы обрабатываются различными способами:

За исключением случаев, документированных в противном случае, методы, использующие перестановку, будут выбрасывать ArrayIndexOutOfBoundsException при обработке канала исключительным индексом.
При первом загрузке недопустимого индекса источника (отрицательного или нет) в перестановку, он частично нормализуется до отрицательного диапазона [-VLENGTH..-1] как будто с помощью wrapIndex(). Такое обращение с исключительными индексами называется частичной оберткой, потому что сохраняет различие между обычными и исключительными индексами, одновременно оборачивая их в смежные диапазоны положительных и неположительных чисел. Частично обернутый индекс впоследствии может быть полностью обернут в положительный диапазон путем добавления конечного смещения VLENGTH.
В некоторых приложениях исключительные индексы используются для «управления» доступом ко второму вектору-источнику. В этих случаях значения индекса исключения, которые находятся в диапазоне [-VLENGTH..-1], циклически перемещаются до допустимого диапазона [0..VLENGTH-1] и используются для второго вектора-источника.
При приведении перестановки к виду другого вида перестановки с меньшим VLENGTH, все индексы повторно проверяются относительно нового VLENGTH, и некоторые могут быть преобразованы в исключительные индексы. В любом случае приведение перестановки никогда не преобразует исключительные индексы в обычные.

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

VectorShuffle, наряду с Vector является классом на основе значения. Операции, чувствительные к тождественности, такие как == , могут давать непредсказуемые результаты или снижать производительность. Кроме того, объекты перестановки векторов могут храниться в локальных переменных и параметрах, а также в качестве static final констант, но хранение их в других полях Java или в элементах массивов, хотя и семантически правильно, может привести к снижению производительности. Наконец, перестановки векторов не следует вычислять в циклах, если это возможно, а вместо этого следует хранить их в неизменяемых локальных переменных или как static final константы.

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

Модификатор и тип	Метод	Описание
`abstract <F> VectorShuffle<F>`	`cast(VectorSpecies<F> species)`	Преобразует эту перестановку в перестановку заданного вида с типом элемента `F`.
`abstract <F> VectorShuffle<F>`	`check(VectorSpecies<F> species)`	Проверяет, что эта перестановка имеет заданный вид, и возвращает эту перестановку без изменений.
`abstract int`	`checkIndex(int index)`	Функция валидации для индексов каналов, которые могут выходить за допустимый диапазон `[0..VLENGTH-1]`.
`abstract VectorShuffle<E>`	`checkIndexes()`	Применение функции валидации `checkIndex()` ко всем каналам, выбрасывая `IndexOutOfBoundsException` если в этой перестановке есть какие-либо исключительные индексы.
`final boolean`	`equals(Object obj)`	Указывает, идентична ли эта перестановка другому объекту.
`static <E> VectorShuffle<E>`	`fromArray(VectorSpecies<E> species, int[] sourceIndexes, int offset)`	Создает перестановку для данного вида из массива `int` начиная со смещения.
`static <E> VectorShuffle<E>`	`fromOp(VectorSpecies<E> species, IntUnaryOperator fn)`	Создает перестановку для данного вида из последовательных значений оператора, примененного к диапазону `[0..VLENGTH-1]`.
`static <E> VectorShuffle<E>`	`fromValues(VectorSpecies<E> species, int... sourceIndexes)`	Создает перестановку для данного вида из ряда индексов источника.
`final int`	`hashCode()`	Возвращает значение хэш-кода для перестановки, основанное на индексах каналов-источников и виде вектора.
`abstract void`	`intoArray(int[] a, int offset)`	Хранит эту перестановку в массиве `int` начиная со смещения.
`static <E> VectorShuffle<E>`	`iota(VectorSpecies<E> species, int start, int step, boolean wrap)`	Создает перестановку, используя индексы источников, установленные в последовательные значения, начинающиеся с `start` и увеличивающиеся на заданный `step`.
`abstract VectorMask<E>`	`laneIsValid()`	Находит все каналы, содержащие допустимые индексы (положительные значения), и возвращает маску, где установлены только эти каналы.
`int`	`laneSource(int i)`	Получает элемент канала `int` канала на индексе канала `i`
`final int`	`length()`	Возвращает количество каналов, обрабатываемых этой перестановкой.
`static <E> VectorShuffle<E>`	`makeUnzip(VectorSpecies<E> species, int part)`	Создает перестановку, которая будет распаковывать конкатенацию двух векторов, поочередно храня входные каналы в один или другой выходной вектор.
`static <E> VectorShuffle<E>`	`makeZip(VectorSpecies<E> species, int part)`	Создает перестановку, которая будет объединять два вектора, поочередно выбирая каналы из одного или другого.
`abstract VectorShuffle<E>`	`rearrange(VectorShuffle<E> s)`	Переупорядочивает элементы каналов этой перестановки, выбирая индексы каналов, управляемые другой перестановкой.
`abstract int[]`	`toArray()`	Возвращает массив `int` , содержащий индексы каналов-источников этой перестановки.
`final String`	`toString()`	Возвращает строковое представление этой перестановки в формате `"Shuffle[0,1,2...]"`, отображая индексы источников в порядке каналов.
`abstract Vector<E>`	`toVector()`	Преобразует эту перестановку в вектор, создавая вектор целочисленных значений, соответствующих индексам каналов-источников перестановки.
`abstract VectorSpecies<E>`	`vectorSpecies()`	Возвращает вид этой перестановки.
`abstract int`	`wrapIndex(int index)`	Функция валидации для индексов каналов, которые могут выходить за допустимый диапазон `[0..VLENGTH-1]`.
`abstract VectorShuffle<E>`	`wrapIndexes()`	Применяет функцию валидации `wrapIndex()` ко всем каналам, заменяя все исключительные индексы обернутыми нормальными индексами.

Методы, объявленные в классе jdk.internal.vm.vector.VectorSupport.VectorPayload

getPayload

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

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

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

vectorSpecies

public abstract VectorSpecies<E> vectorSpecies()

Возвращает вид сдвига.

Возвращает:: вид сдвига

length

public final int length()

Возвращает количество обработанных дорожек сдвига. Это то же самое, что и VLENGTH любого вектора, на котором он работает.

Возвращает:: количество дорожек сдвига

cast

public abstract <F> VectorShuffle<F> cast(VectorSpecies<F> species)

Преобразует этот сдвиг в сдвиг заданного вида элемента типа F. Различные индексы источников дорожек не изменяются. Исключительные индексы остаются исключительными, а допустимые индексы остаются допустимыми.

Параметры типа:: F - упакованный тип элемента вида
Параметры:: species - вид желаемого сдвига
Возвращает:: сдвиг, преобразованный по форме и типу элемента
Исключение:: IllegalArgumentException - если длина этого сдвига и длина вида отличаются

check

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

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

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

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

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

Параметры:

species - требуемый вид

Возвращает:

тот же сдвиг

Исключение:

ClassCastException - если вид сдвига неверен

См. также:

checkIndex

public abstract int checkIndex(int index)

Функция валидации для индексов дорожек, которые могут выходить за допустимый диапазон [0..VLENGTH-1]. Если index находится в этом диапазоне, он возвращается без изменений. В противном случае выбрасывается IndexOutOfBoundsException.

Параметры:

index - индекс дорожки

Возвращает:

index

Исключение:

IndexOutOfBoundsException - если index не меньше VLENGTH, или отрицательно

См. также:

wrapIndex(int)
checkIndexes()

wrapIndex

public abstract int wrapIndex(int index)

Функция валидации для индексов дорожек, которые могут выходить за допустимый диапазон [0..VLENGTH-1]. index приводится к этому диапазону путем добавления или вычитания подходящего кратного VLENGTH. Конкретно, индекс сводится к необходимому диапазону, вычисляя значение length-floor, где floor=vectorSpecies().loopBound(length) — следующее меньшее кратное VLENGTH. Если VLENGTH является степенью двойки, то уменьшенный индекс также равен index & (VLENGTH - 1).

Параметры:

index - индекс дорожки

Возвращает:

index, откорректированный до диапазона [0..VLENGTH-1 подходящим кратным VLENGTH

См. также:

checkIndexes

public abstract VectorShuffle<E> checkIndexes()

Применяет функцию валидации checkIndex() ко всем дорожкам, выбрасывая IndexOutOfBoundsException если в этом сдвиге есть какие-либо исключительные индексы.

Возвращает:

текущий сдвиг, без изменений

Исключение:

IndexOutOfBoundsException - если какие-либо дорожки в этом сдвиге содержат исключительные индексы

См. также:

checkIndex(int)
wrapIndexes()

wrapIndexes

public abstract VectorShuffle<E> wrapIndexes()

Применяет функцию валидации wrapIndex() ко всем дорожкам, заменяя любые исключительные индексы обернутыми нормальными индексами.

Возвращает:

текущий сдвиг со всеми обернутыми исключительными индексами

См. также:

wrapIndex(int)
checkIndexes()

laneIsValid

public abstract VectorMask<E> laneIsValid()

Находит все дорожки, содержащие допустимые индексы (неотрицательные значения), и возвращает маску, где установлены именно эти дорожки.

Возвращает:

маска дорожек, содержащих допустимые индексы источника

См. также:

checkIndexes()

fromValues

public static <E> VectorShuffle<E> fromValues(VectorSpecies<E> species, int... sourceIndexes)

Создаёт сдвиг для заданного вида из серии индексов источника.

Для каждой дорожки сдвига, где N — индекс дорожки сдвига, значение индекса N проверяется на соответствие виду VLENGTH, и (если не соответствует) частично обертывается в исключительный индекс в диапазоне [-VLENGTH..-1].

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

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

Параметры:

species - вид сдвига

sourceIndexes - индексы источника, из которых будет черпать сдвиг

Возвращает:

сдвиг, где индекс источника каждой дорожки установлен на заданное значение int, частично обернутый, если исключительный

Исключение:

IndexOutOfBoundsException - если sourceIndexes.length != VLENGTH

См. также:

VectorSpecies.shuffleFromValues(int...)

fromArray

public static <E> VectorShuffle<E> fromArray(VectorSpecies<E> species, int[] sourceIndexes, int offset)

Создаёт сдвиг для заданного вида из массива int начиная с смещения.

Для каждой дорожки сдвига, где N — индекс дорожки сдвига, элемент массива с индексом offset + N проверяется на соответствие виду VLENGTH, и (если не соответствует) частично обертывается в исключительный индекс в диапазоне [-VLENGTH..-1].

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

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

Параметры:

species - вид сдвига

sourceIndexes - индексы источника, из которых будет черпать сдвиг

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

Возвращает:

Исключение:

IndexOutOfBoundsException - если offset < 0, или offset > sourceIndexes.length - VLENGTH

См. также:

VectorSpecies.shuffleFromArray(int[], int)

fromOp

public static <E> VectorShuffle<E> fromOp(VectorSpecies<E> species, IntUnaryOperator fn)

Создаёт сдвиг для заданного вида из последовательных значений оператора, применённого к диапазону [0..VLENGTH-1].

Следует позаботиться о том, чтобы значения VectorShuffle, созданные с помощью этого метода, потреблялись как константы, чтобы обеспечить оптимальное генерирование кода. Например, значения сдвига можно хранить в static final полях или не изменяемых в цикле локальных переменных.

Этот метод ведет себя так, как если бы сдвиг был создан из массива индексов, отображённых следующим образом:


   int[] a = new int[species.length()];
   for (int i = 0; i < a.length; i++) {
       a[i] = fn.applyAsInt(i);
   }
   return VectorShuffle.fromArray(a, 0);

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

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

Параметры:

species - вид сдвига

fn - функция отображения индекса дорожки

Возвращает:

сдвиг отображенных индексов

См. также:

VectorSpecies.shuffleFromOp(IntUnaryOperator)

iota

public static <E> VectorShuffle<E> iota(VectorSpecies<E> species, int start, int step, boolean wrap)

Создаёт перемешивание, используя исходные индексы, установленные в последовательные значения, начиная с start и шагом, заданным step.

Этот метод возвращает значение выражения VectorShuffle.fromOp(species, i -> R(start + i * step)), где R - wrapIndex, если wrap имеет значение true, и является тождественной функцией в противном случае.

Если wrap имеет значение false, каждый индекс проверяется на соответствие виду VLENGTH, и (если не соответствует) частично обёртывается до исключительного индекса в диапазоне [-VLENGTH..-1]. В противном случае, если wrap имеет значение true, каждый индекс также сводится, как если бы по wrapIndex, к допустимому диапазону [0..VLENGTH-1].

API Note:

Параметр wrap следует установить в значение


 true

, если недопустимые исходные индексы должны быть обернуты. В противном случае, установка его в значение false позволяет проверять недопустимые исходные индексы на соответствие диапазону в последующих операциях, таких как unary rearrange.

Type Parameters:

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

Parameters:

species - вид перемешивания

start - начальное значение последовательности исходных индексов

step - разность между смежными исходными индексами

wrap - следует ли обёртывать результирующие индексы

Returns:

перемешивание последовательных индексов регистров, возможно обернутых

See Also:

VectorSpecies.iotaShuffle(int,int,boolean)

makeZip

public static <E> VectorShuffle<E> makeZip(VectorSpecies<E> species, int part)

Создаёт перемешивание, которое будет объединять два вектора, поочерёдно выбирая регистры из одного или другого. Логический результат объединения в два раза больше размера любого входного вектора, и поэтому расширенный результат разбивается на две физические части, выбираемые по номеру части. Например, объединение двух векторов [a,b,c,d] и [1,2,3,4] даст расширенный логический результат [a,1,b,2,c,3,d,4], который должен быть получен в двух частях, [a,1,b,2] и [c,3,d,4].

Этот метод возвращает значение выражения VectorShuffle.fromOp(species, i -> i/2 + (i%2)*VLENGTH + P, где P - part*VLENGTH/2.

Обратите внимание, что исходные индексы в нечётных регистрах перемешивания будут недопустимыми индексами (>= VLENGTH, или < 0 после частичной нормализации), которые будут выбираться из второго вектора.

Type Parameters:

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

Parameters:

species - вид перемешивания

part - номер части результата (ноль или один)

Returns:

перемешивание, которое объединяет два вектора в 2*VLENGTH регистров, возвращая выбранную часть

Throws:

ArrayIndexOutOfBoundsException - если part не равно нулю или единице

See Also:

makeUnzip

public static <E> VectorShuffle<E> makeUnzip(VectorSpecies<E> species, int part)

Создаёт перемешивание, которое будет распаковывать конкатенацию двух векторов, поочерёдно сохраняя входные регистры в один или другой выходной вектор. Поскольку логический результат распаковки в два раза больше размера любого входного вектора, расширенный результат разбивается на две физические части, выбираемые по номеру части. Например, распаковка двух векторов [a,1,b,2][c,3,d,4] даст результат в двух частях, [a,b,c,d] и [1,2,3,4].

Этот метод возвращает значение выражения VectorShuffle.fromOp(species, i -> i*2+part.

Обратите внимание, что исходные индексы в верхней половине перемешивания будут недопустимыми индексами (>= VLENGTH, или < 0 после частичной нормализации), которые будут выбираться из второго вектора.

Type Parameters:

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

Parameters:

species - вид перемешивания

part - номер части результата (ноль или один)

Returns:

перемешивание, которое распаковывает 2*VLENGTH регистров в два вектора, возвращая выбранную часть

Throws:

ArrayIndexOutOfBoundsException - если part не равно нулю или единице

See Also:

toArray

public abstract int[] toArray()

Возвращает массив int содержащий индексы исходных регистров этого перемешивания.

Этот метод работает так, как если бы он сохранил это перемешивание в выделенном массиве (используя intoArray) и возвращает этот массив следующим образом:


   int[] a = new int[this.length()];
   VectorShuffle.intoArray(a, 0);
   return a;

API Note:: Индексы исходных регистров перемешивания всегда находятся в диапазоне от -VLENGTH до VLENGTH-1 . Исходный индекс является исключительным тогда и только тогда, когда он отрицателен.
Returns:: массив, содержащий индексы исходных регистров этого перемешивания

intoArray

public abstract void intoArray(int[] a, int offset)

Сохраняет это перемешивание в массив int начиная со смещения.

Для каждого регистра перемешивания N, индекс исходного регистра, хранимого для этого элемента регистра, хранится в элементе массива a[offset+N].

API Note:: Индексы исходных регистров перемешивания всегда находятся в диапазоне от -VLENGTH до VLENGTH-1.
Parameters:: a - массив типа int[]; offset - смещение в массиве
Throws:: IndexOutOfBoundsException - если offset < 0 или offset > a.length - this.length()

toVector

public abstract Vector<E> toVector()

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

Этот метод ведет себя так, как если бы он возвращал результат создания вектора, заданного массивом int , полученным из элементов регистров этого перемешивания, как показано ниже:


   int[] sa = this.toArray();
   $type$[] va = new $type$[a.length];
   for (int i = 0; i < a.length; i++) {
       va[i] = ($type$) sa[i];
   }
   return IntVector.fromArray(va, 0);

API Note:: Индексы исходных регистров перемешивания всегда находятся в диапазоне от -VLENGTH до VLENGTH-1. Эти значения преобразуются в ETYPE результирующего вектора, даже если он имеет тип с плавающей запятой.
Returns:: векторное представление этого перемешивания

laneSource

public int laneSource(int i)

Получает элемент регистра int в индексе регистра i

Parameters:: i - индекс регистра
Returns:: элемент регистра int в индексе регистра i

rearrange

public abstract VectorShuffle<E> rearrange(VectorShuffle<E> s)

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

Для каждого регистра указанного перемешивания, с индексом регистра N и элементом регистра I, выбирается элемент регистра в I из этого перемешивания и помещается в результирующее перемешивание в N.

Parameters:: s - перемешивание, контролирующее выбор индекса регистра
Returns:: переупорядочение элементов регистров этого перемешивания

toString

public final String toString()

Возвращает строковое представление этого перемешивания в виде "Shuffle[0,1,2...]", сообщая индексы исходных регистров в порядке регистров.

Overrides:: toString в классе Object
Returns:: строка вида "Shuffle[0,1,2...]"

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:

© 1993, 2021, 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/17/docs/api/jdk.incubator.vector/jdk/incubator/vector/VectorShuffle.html