Класс VectorShuffle<E>

java.lang.Object

jdk.incubator.vector.VectorShuffle<E>

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

public abstract class VectorShuffle<E> extends Object

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

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)`	Создаёт шейф для заданного вида из серии индексов источников.
`protected final Object`	`getPayload()`
`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()` ко всем полосам, заменяя любые исключительные индексы обернутыми нормальными индексами.

Методы, объявленные в классе 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

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 - если какие-либо полосы в этом сдвиге содержат исключительные индексы

См. также:

wrapIndexes

public abstract VectorShuffle<E> wrapIndexes()

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

Возвращает:

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

См. также:

laneIsValid

public abstract VectorMask<E> laneIsValid()

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

Возвращает:

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

См. также:

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

См. также:

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

См. также:

fromOp

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

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

Для каждой полосы сдвига, где N - индекс полосы сдвига, N-е значение индекса проверяется на соответствие виду VLENGTH, и (если не соответствует) частично обёртывается в исключительный индекс в диапазоне [-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 - функция отображения индекса полосы

Возвращает:

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

См. также:

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:

Параметр wrap должен быть установлен в


 true

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

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

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

Параметры:

species - вид сдвига

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

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

wrap - обёртывать ли полученные индексы

Возвращает:

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

См. также:

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:

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/VectorShuffle.html