Интерфейс VectorSpecies<E>
- Параметры типа:
E- упакованная версияETYPE, типа элементов вектора
public interface VectorSpecies<E>
- Примечание API:
- Пользовательский код не должен реализовывать этот интерфейс. В одном из будущих выпусков для этого типа может быть установлено ограничение, согласно которому его реализации должны принадлежать тому же пакету.
- Примечание по реализации:
- Строковое представление экземпляра этого интерфейса будет иметь вид "Species[ETYPE, VLENGTH, SHAPE]", где
ETYPE— это примитивный тип lane,VLENGTH— это число lane вектора, связанное с данным видом, аSHAPE— это форма вектора, связанная с данным видом.Объекты вида вектора можно хранить в локальных переменных, параметрах и в виде констант
static final, однако их хранение в других полях Java или элементах массива, хотя и допустимо с точки зрения семантики, может привести к снижению производительности.
Краткое описание методов
| Модификатор и тип | Метод | Описание |
|---|---|---|
Vector |
broadcast |
Возвращает вектор данного вида, все элементы lane которого установлены в примитивное значение e. |
<F> VectorSpecies |
check |
Проверяет, что тип элементов данного вида соответствует заданному, и возвращает этот вид без изменений. |
long |
checkValue |
Проверяет, что данный вид может представлять заданное значение элемента, и возвращает это значение без изменений. |
int |
elementSize() |
Возвращает размер lane в битах для векторов данного вида. |
static int |
elementSize |
Возвращает размер в битах заданного типа элемента вектора ( ETYPE). |
Class |
elementType() |
Возвращает примитивный тип элементов векторов данного вида. |
boolean |
equals |
Указывает, идентичен ли данный вид другому объекту. |
Vector |
fromArray |
Возвращает вектор данного вида, элементы lane которого инициализируются из заданного массива, начиная с заданного смещения. |
Vector |
fromMemorySegment |
Загружает вектор данного вида из сегмента памяти, начиная со смещения в сегменте памяти. |
int |
hashCode() |
Возвращает хеш-код вида, основанный на форме вектора и типе элементов. |
VectorMask |
indexInRange |
Возвращает маску данного вида, в которой установлены только lane с индексом N, для которых скорректированный индекс N+offset входит в диапазон [0..limit-1]. |
VectorMask |
indexInRange |
Возвращает маску данного вида, в которой установлены только lane с индексом N, для которых скорректированный индекс N+offset входит в диапазон [0..limit-1]. |
VectorShuffle |
iotaShuffle |
Создает shuffle, используя исходные индексы, заданные последовательными значениями, начиная с start и увеличивая их на заданное step. |
int |
length() |
Возвращает количество lane в векторе данного вида. |
VectorMask |
loadMask |
Возвращает маску данного вида, элементы lane которой инициализируются из заданного массива, начиная с заданного смещения. |
int |
loopBound |
Функция управления циклом, возвращающая наибольшее кратное VLENGTH, которое меньше или равно заданному значению length. |
long |
loopBound |
Функция управления циклом, возвращающая наибольшее кратное VLENGTH, которое меньше или равно заданному значению length. |
VectorMask |
maskAll |
Возвращает маску данного вида, в которой каждая lane устанавливается или сбрасывается в соответствии с заданным логическим значением, распространяемым на все lane. |
Class |
maskType() |
Возвращает тип маски вектора для данного вида. |
static <E> VectorSpecies |
of |
Находит вид для заданного типа элементов и формы. |
static <E> VectorSpecies |
ofLargestShape |
Находит наибольший вид вектора для заданного типа элементов. |
static <E> VectorSpecies |
ofPreferred |
Находит вид, предпочтительный для текущей платформы для заданного типа элементов вектора. |
int |
partLimit |
Для данного вида и второго вида сообщает итоговое расширение или сжатие при (возможно) изменяющем размер приведении с переинтерпретацией или lane-wise conversion от данного вида ко второму. |
VectorShuffle |
shuffleFromArray |
Создает shuffle для данного вида из массива int, начиная с заданного смещения. |
VectorShuffle |
shuffleFromOp |
Создает shuffle для данного вида из последовательных значений оператора, примененного к диапазону [0..VLENGTH-1]. |
VectorShuffle |
shuffleFromValues |
Создает shuffle для данного вида из последовательности исходных индексов. |
String |
toString() |
Возвращает строку вида "Species[ETYPE, VLENGTH, SHAPE]", где ETYPE — это примитивный тип lane, VLENGTH — это число lane вектора, связанное с данным видом, а
SHAPE — это форма вектора, связанная с данным видом. |
int |
vectorBitSize() |
Возвращает общий размер вектора в битах для любого вектора данного вида. |
int |
vectorByteSize() |
Возвращает общий размер вектора в байтах для любого вектора данного вида. |
VectorShape |
vectorShape() |
Возвращает форму векторов, создаваемых данным видом. |
Class |
vectorType() |
Возвращает тип вектора данного вида. |
<F> VectorSpecies |
withLanes |
Находит вид с заданным типом элементов и той же формой, что и у данного вида. |
VectorSpecies |
withShape |
Находит вид с заданной формой и тем же типом элементов, что и у данного вида. |
Vector |
zero() |
Возвращает вектор данного вида, все элементы lane которого установлены в примитивное значение по умолчанию, (ETYPE)0. |
Подробное описание методов
elementType
Class<E> elementType()
- Возвращает:
- примитивный тип элемента (
ETYPE) - См. также:
vectorType
Class<? extends Vector<E>> vectorType()
- Возвращает:
- тип вектора этого вида
maskType
Class<? extends VectorMask<E>> maskType()
- Возвращает:
- тип маски
elementSize
int elementSize()
- Возвращает:
- размер элемента в битах
vectorShape
VectorShape vectorShape()
- Возвращает:
- форму любого вектора этого вида
length
int length()
- Примечание к API:
- Это также количество дорожек маски или перестановки, связанных с вектором этого вида.
- Возвращает:
- количество дорожек вектора
vectorBitSize
int vectorBitSize()
this.vectorShape().vectorBitSize().- Примечание к API:
- Этот размер может отличаться от размера в битах маски или перестановки этого вида.
- Возвращает:
- общий размер вектора в битах
vectorByteSize
int vectorByteSize()
this.vectorShape().vectorBitSize() / Byte.SIZE.- Примечание к API:
- Этот размер может отличаться от размера в битах маски или перестановки этого вида.
- Возвращает:
- общий размер вектора в байтах
loopBound
int loopBound(int length)
VLENGTH, которое меньше или равно заданному значению length. Здесь VLENGTH — результат this.length(), а length интерпретируется как количество дорожек. Полученное значение R удовлетворяет неравенству: R <= length < R+VLENGTH
В частности, этот метод вычисляет length - floorMod(length, VLENGTH), где floorMod вычисляет остаток, округляя частное в сторону минус бесконечности. Если VLENGTH является степенью двойки, результат также равен length & ~(VLENGTH - 1).
- Параметры:
-
length— входная длина - Возвращает:
- наибольшее кратное длины вектора, не превышающее заданную длину
- Выбрасывает:
-
IllegalArgumentException— еслиlengthотрицательно и в результате переполнения получилось бы положительное значение - См. также:
loopBound
long loopBound(long length)
VLENGTH, которое меньше или равно заданному значению length. Здесь VLENGTH — результат this.length(), а length интерпретируется как количество дорожек. Полученное значение R удовлетворяет неравенству: R <= length < R+VLENGTH
В частности, этот метод вычисляет length - floorMod(length, VLENGTH), где floorMod вычисляет остаток, округляя частное в сторону минус бесконечности. Если VLENGTH является степенью двойки, результат также равен length & ~(VLENGTH - 1).
- Параметры:
-
length— входная длина - Возвращает:
- наибольшее кратное длины вектора, не превышающее заданную длину
- Выбрасывает:
-
IllegalArgumentException— еслиlengthотрицательно и в результате переполнения получилось бы положительное значение - Начиная с версии:
- 19
- См. также:
indexInRange
VectorMask<E> indexInRange(int offset, int limit)
N+offset находится в диапазоне [0..limit-1]. Этот метод возвращает значение выражения maskAll(true).indexInRange(offset, limit)
- Параметры:
-
offset— начальный индекс -
limit— верхняя граница диапазона индексов (не включительно) - Возвращает:
- маску, в которой не установлены выходящие за диапазон дорожки
- См. также:
indexInRange
VectorMask<E> indexInRange(long offset, long limit)
N+offset находится в диапазоне [0..limit-1]. Этот метод возвращает значение выражения maskAll(true).indexInRange(offset, limit)
- Параметры:
-
offset— начальный индекс -
limit— верхняя граница диапазона индексов (не включительно) - Возвращает:
- маску, в которой не установлены выходящие за диапазон дорожки
- Начиная с версии:
- 19
- См. также:
check
<F> VectorSpecies<F> check(Class<F> elementType)
elementType == elementType()
? this
: throw new ClassCastException().- Параметры типа:
F— обернутый тип элемента требуемого типа дорожки- Параметры:
-
elementType— требуемый тип дорожки - Возвращает:
- тот же вид
- Выбрасывает:
-
ClassCastException— если вид имеет неверный тип элемента - См. также:
partLimit
int partLimit(VectorSpecies<?> outputSpecies, boolean lanewise)
lane-wise conversion из этого вида во второй. Знак и величина возвращаемого значения зависят от разницы размеров предлагаемых входной и выходной форм, а также (необязательно, если lanewise равно true) от разницы размеров предлагаемых входных и выходных дорожек. - Сначала определяется логический размер результата. Если
lanewiseравно false, этот размер равен размеру входногоVSHAPE. Еслиlanewiseравно true, логический размер результата равен произведению входногоVLENGTHна размер выходногоETYPE. - Затем логический размер результата сравнивается с размером предлагаемой выходной формы, чтобы определить, поместится ли в ней результат.
- Если логический результат точно помещается в выходную форму, возвращаемое значение равно нулю, что означает отсутствие итогового расширения или сжатия.
- Если логический результат превышает размер выходной формы, возвращаемое значение равно отношению (больше единицы) логического размера результата к (меньшему) размеру выхода. Это отношение можно рассматривать как долю «отбрасываемых входных битов», которые необходимо удалить из входных данных, чтобы результат поместился в выходной вектор. Оно также представляет собой предел части — исключительную верхнюю границу параметра
partметода, преобразующего входной вид в выходной. - Если логический результат помещается в выходную форму с запасом, возвращаемое значение — отрицательное число, модуль которого равен отношению (больше единицы) размера выхода к (меньшему) логическому размеру результата. Это отношение можно рассматривать как долю «дополнительных битов заполнения», которые необходимо добавить к логическому результату, чтобы заполнить выходной вектор. Оно также представляет собой предел части — исключительную нижнюю границу параметра
partметода, преобразующего входной вид в выходной.
- Параметры:
-
outputSpecies— предлагаемый выходной вид -
lanewise— учитывать ли размеры дорожек - Возвращает:
- указание на изменение размера в виде знакового отношения или нуля
- См. также:
withLanes
<F> VectorSpecies<F> withLanes(Class<F> newType)
VectorSpecies.of(newType, this.vectorShape()).- Параметры типа:
F— обернутый тип элемента- Параметры:
-
newType— новый тип элемента - Возвращает:
- вид для нового типа элемента и той же формы
- Выбрасывает:
-
IllegalArgumentException— если для заданного сочетания типа элемента и формы не существует такого вида или если заданный тип не является допустимымETYPE - См. также:
withShape
VectorSpecies<E> withShape(VectorShape newShape)
VectorSpecies.of(this.elementType(), newShape).- Параметры:
-
newShape— новая форма - Возвращает:
- вид для того же типа элемента и новой формы
- Выбрасывает:
-
IllegalArgumentException— если для заданного сочетания типа элемента и формы не существует такого вида - См. также:
of
static <E> VectorSpecies<E> of(Class<E> elementType, VectorShape shape)
- Параметры типа:
E— обернутый тип элемента- Параметры:
-
elementType— тип элемента -
shape— форма - Возвращает:
- вид для заданного типа элемента и формы
- Выбрасывает:
-
IllegalArgumentException— если для заданного сочетания типа элемента и формы не существует такого вида или если заданный тип не является допустимымETYPE - См. также:
ofLargestShape
static <E> VectorSpecies<E> ofLargestShape(Class<E> etype)
Возвращаемый вид — это вид, выбранный платформой и имеющий форму с максимально возможным размером в битах для заданного типа элементов. На некоторых платформах соответствующая форма вектора может не поддерживать другие типы элементов векторов, что может ограничить применимость приведения с переинтерпретацией. Векторные алгоритмы, которым требуются приведения с переинтерпретацией, будут более переносимыми, если они используют предпочтительный вид платформы.
- Параметры типа:
E— упакованный тип элемента- Параметры:
-
etype— тип элемента - Возвращает:
- предпочтительный вид для типа элемента
- Исключения:
-
IllegalArgumentException— если для типа элемента не существует такого вида или если заданный тип не является допустимымETYPE - См. также:
ofPreferred
static <E> VectorSpecies<E> ofPreferred(Class<E> etype)
VectorSpecies.of(etype, VectorShape.preferredShape()). Этот вид выбирается платформой так, чтобы иметь максимально возможную форму, поддерживающую все типы элементов векторов. Это имеет следующие последствия:
- Все предпочтительные виды для разных типов элементов будут иметь одинаковую базовую форму.
- Все векторы, созданные на основе предпочтительных видов, будут иметь общий размер в битах и информационную емкость.
- Приведения с переинтерпретацией между векторами предпочтительных видов не будут ни усекать элементы, ни заполнять их значениями по умолчанию.
- Для любого конкретного типа элементов некоторые платформы могут предоставлять более крупную форму вектора, которая (в качестве компромисса) не поддерживает все возможные типы элементов.
- Примечание по реализации:
- На многих платформах между
ofLargestShapeиofPreferredнет поведенческих различий, поскольку предпочтительная форма обычно также является самой большой доступной формой для каждого типа элементов. Поэтому большинство векторных алгоритмов будут работать эффективно и безofLargestShape. - Параметры типа:
E— упакованный тип элемента- Параметры:
-
etype— тип элемента - Возвращает:
- предпочтительный вид для этого типа элемента
- Исключения:
-
IllegalArgumentException— если для типа элемента не существует такого вида или если заданный тип не является допустимымETYPE - См. также:
elementSize
static int elementSize(Class<?> elementType)
ETYPE). Тип элемента должен быть допустимым ETYPE, а не типом-оболочкой или другим объектным типом. Аргумент типа элемента должен быть зеркалом допустимого типа вектора ETYPE, например byte.class, int.class или double.class. Размер в битах такого типа — это константа SIZE соответствующего класса-оболочки, например Byte.SIZE, Integer.SIZE или Double.SIZE.- Параметры:
-
elementType— тип элемента вектора (ETYPE) - Возвращает:
- размер в битах
elementType, например 32 дляint.class - Исключения:
-
IllegalArgumentException— если заданный аргументelementTypeне является допустимым типом вектораETYPE
zero
Vector<E> zero()
(ETYPE)0. Эквивалентно IntVector.zero(this) или эквивалентному методу zero для типа вектора, соответствующего этому виду.- Возвращает:
- нулевой вектор заданного вида
- См. также:
fromArray
Vector<E> fromArray(Object a, int offset)
ETYPE. Эквивалентно IntVector.fromArray(this,a,offset) или эквивалентному методу fromArray для типа вектора, соответствующего этому виду.- Параметры:
-
a— массив типаETYPEдля этого вида -
offset— индекс первого загружаемого значения элемента - Возвращает:
- вектор заданного вида, заполненный значениями из массива
- Исключения:
-
IndexOutOfBoundsException— еслиoffset+N < 0илиoffset+N >= a.lengthдля любого элементаNв векторе - См. также:
fromMemorySegment
Vector<E> fromMemorySegment(MemorySegment ms, long offset, ByteOrder bo)
Эквивалентно IntVector.fromMemorySegment(this,ms,offset,bo) для типа вектора, соответствующего этому виду.
- Параметры:
-
ms— сегмент памяти -
offset— смещение в сегменте памяти -
bo— требуемый порядок байтов - Возвращает:
- вектор заданного вида, заполненный данными из сегмента памяти
- Исключения:
-
IndexOutOfBoundsException— еслиoffset+N*ESIZE < 0илиoffset+(N+1)*ESIZE > a.lengthдля любого элементаNв векторе - Начиная с версии:
- 19
- См. также:
loadMask
VectorMask<E> loadMask(boolean[] bits, int offset)
VectorMask.fromArray(this,a,offset).- Параметры:
-
bits— массивboolean -
offset— смещение в массиве - Возвращает:
- маска, загруженная из массива
boolean - Исключения:
-
IndexOutOfBoundsException— еслиoffset+N < 0илиoffset+N >= a.lengthдля любого элементаNв маске вектора - См. также:
maskAll
VectorMask<E> maskAll(boolean bit)
- Параметры:
-
bit— заданный бит маски для копирования - Возвращает:
- маску, в которой каждый элемент установлен или сброшен в соответствии с заданным битом
- См. также:
broadcast
Vector<E> broadcast(long e)
e. Этот метод возвращает значение выражения: EVector.broadcast(this, (ETYPE)e), где EVector — класс вектора, соответствующий ETYPE этого вида. Значение long должно точно представляться типом ETYPE, чтобы выполнялось e==(long)(ETYPE)e.
- Параметры:
-
e— значение для распространения - Возвращает:
- вектор, в котором все элементы установлены в примитивное значение
e - Исключения:
-
IllegalArgumentException— если заданное значениеlongне может быть представлено видом вектораETYPE - См. также:
checkValue
long checkValue(long e)
long должно точно представляться типом ETYPE вида вектора, чтобы выполнялось e==(long)(ETYPE)e. Эффект аналогичен следующему псевдокоду: e == (long)(ETYPE)e
? e
: throw new IllegalArgumentException().- Параметры:
-
e— проверяемое значение - Возвращает:
e- Исключения:
-
IllegalArgumentException— если заданное значениеlongне может быть представлено видом вектораETYPE - См. также:
shuffleFromValues
VectorShuffle<E> shuffleFromValues(int... sourceIndexes)
Для каждого элемента перестановки, где N — индекс элемента перестановки, значение индекса под номером N проверяется на соответствие VLENGTH вида и, если оно недопустимо, частично преобразуется в исключительный индекс в диапазоне [-VLENGTH..-1].
- Параметры:
-
sourceIndexes— исходные индексы, из которых будет выбирать перестановка - Возвращает:
- перестановку, в которой исходный индекс каждого элемента задан значением
intи частично преобразован, если оно недопустимо - Исключения:
-
IndexOutOfBoundsException— еслиsourceIndexes.length != VLENGTH - См. также:
shuffleFromArray
VectorShuffle<E> shuffleFromArray(int[] sourceIndexes, int offset)
int, начиная со смещения. Для каждого элемента перестановки, где N — индекс элемента перестановки, элемент массива с индексом i + N проверяется на соответствие VLENGTH вида и, если он недопустим, частично преобразуется в исключительный индекс в диапазоне [-VLENGTH..-1].
- Параметры:
-
sourceIndexes— исходные индексы, из которых будет выбирать перестановка -
offset— смещение в массиве - Возвращает:
- перестановку, в которой исходный индекс каждого элемента задан значением
intи частично преобразован, если оно недопустимо - Исключения:
-
IndexOutOfBoundsException— еслиoffset < 0илиoffset > sourceIndexes.length - VLENGTH - См. также:
shuffleFromOp
VectorShuffle<E> shuffleFromOp(IntUnaryOperator fn)
[0..VLENGTH-1]. Для каждой полосы перестановки, где N — индекс полосы перестановки, значение индекса N проверяется на соответствие виду VLENGTH и (если оно недопустимо) частично преобразуется в исключительный индекс в диапазоне [-VLENGTH..-1].
Следует позаботиться о том, чтобы значения VectorShuffle, полученные этим методом, использовались как константы для оптимальной генерации кода. Например, значения перестановки можно хранить в полях static final или в локальных переменных, инвариантных относительно цикла.
Этот метод работает так, как если бы перестановка создавалась из массива сопоставленных индексов следующим образом:
int[] a = new int[VLENGTH];
for (int i = 0; i < a.length; i++) {
a[i] = fn.applyAsInt(i);
}
return VectorShuffle.fromArray(this, a, 0);
- Параметры:
-
fn— функция сопоставления индексов полос - Возвращает:
- перестановку сопоставленных индексов
- См. также:
iotaShuffle
VectorShuffle<E> iotaShuffle(int start, int step, boolean wrap)
start и увеличивая их на указанное значение step. Этот метод возвращает значение выражения VectorSpecies.shuffleFromOp(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, проверять выход исходных индексов за границы диапазона. - Параметры:
-
start— начальное значение последовательности исходных индексов, обычно0 -
step— разность между соседними исходными индексами, обычно1 -
wrap— указывает, следует ли оборачивать результирующие индексы по модулюVLENGTH - Возвращает:
- перестановку последовательных индексов полос
- См. также:
toString
String toString()
ETYPE — примитивный тип полосы, VLENGTH — количество полос вектора, связанное с видом, а
SHAPE — форма вектора, связанная с видом.equals
boolean equals(Object obj)
hashCode
© 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/VectorSpecies.html