モジュール jdk.incubator.vector

パッケージ jdk.incubator.vector

クラスVectorShuffle<E>

java.lang.Object

jdk.incubator.vector.VectorShuffle<E>

型パラメータ:

E - ETYPEのボックス版、ベクトルの要素型

public abstract class VectorShuffle<E> extends Object

VectorShuffleは、「ソース索引」と呼ばれる、順序付けされた不変の一連のint値を表します。各ソース索引は、互換性のあるVectorからソース・レーンを数値で選択します。

同じ「要素型」 (ETYPE)およびshapeのVectorShuffleおよびVectorには同じ数のレーンがあるため、(具体的には、そのvector speciesには互換性があります)との互換性があります。

シャッフルは、rearrangeメソッドを使用して(compatible)ソース・ベクトルに適用されます。

シャッフルにはベクトル種から導出されたレーン構造がありますが、レーン索引はレーン値ではなくintとして格納されます。

このメソッドは、ソース・ベクトルへのランダム・アクセスによってレーン値を収集し、ソース索引を参照してレーンを選択します。 ソース索引がシャッフルに複数回出現する場合は、選択したレーン値が結果に複数回コピーされます。 特定のレーンがソース索引によって選択されない場合、そのレーン値は無視されます。 結果のベクトルには、シャッフルのソース・インデックスによって選択されたすべてのソース・レーン値が含まれます。 結果のレーン値は、元のベクトル・レーンの順序ではなく、シャッフル・ソース索引に従って順序付けされます。

各シャッフルには、シャッフルが演算するベクトルの互換性を決定するvectorSpecies()プロパティがあります。 これにより、シャッフルのlength()は常に、それが演算するベクトルのVLENGTHと等しくなります。 要素種とシャッフル種のシェイプは、シャッフルの動作とは直接関係ありません。 レーン数が一定であるかぎり、シャッフルは他のレーン・タイプへのconvertedにすることが容易です。

その内部状態では、シャッフルは常に[-VLENGTH..VLENGTH-1]からの狭い範囲の整数値を保持します。 正の数は自己説明的で、任意のソース・ベクトルに適用されるレーン番号です。 負の数(存在する場合)は、シャッフルが有効なレーン索引ではないraw整数値から作成されたことを示す符号です。

シャッフルに負の数で表される無効なソース索引は、「例外索引」と呼ばれます。

例外的な索引は様々な方法で処理されます:

• 特に明記されていないかぎり、レーンが例外的なインデックスによって処理されると、シャッフル使用メソッドはArrayIndexOutOfBoundsExceptionをスローします。
• 無効なソース索引(負であるかどうか)が最初にシャッフルにロードされると、wrapIndex()による場合と同様に、[-VLENGTH..-1]の負の範囲に部分的に正規化されます。 この例外的な索引の処理は、正の数と正でない数の隣接する範囲にラップしながら、通常の索引と例外的な索引の区別を保持するため、「部分ラッピング」と呼ばれます。 部分的にラップされた索引は、VLENGTHの最終オフセットを追加することで、後で完全に正の範囲にラップできます。
• 一部のアプリケーションでは、別のソース・ベクトルへの"steer"アクセスに使用される例外的な索引。 そのような場合、[-VLENGTH..-1]の範囲内にある例外索引値は、有効な範囲である[0..VLENGTH-1]まで循環され、2番目のソース・ベクトルで使用されます。
• VLENGTHが小さい別のシャッフル種からシャッフルがキャストされると、すべての索引が新しいVLENGTHに対して再検証され、一部の索引が例外索引に変換される可能性があります。 いずれの場合も、シャッフル・キャスティングは例外的なインデックスを通常のインデックスに変換しません。

値ベースのクラスとアイデンティティ演算

VectorShuffleは、Vectorとともにvalue-basedクラスです。 ==などのアイデンティティ依存の演算では、予期しない結果が発生したり、パフォーマンスが低下する可能性があります。 また、ベクトル・シャッフル・オブジェクトは、ローカルおよびパラメータに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)	このシャッフルを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)	レーン索引iのintレーン要素を取得
final int	length()	このシャッフルによって処理されたレーンの数を返します。
static <E> VectorShuffle<E>	makeUnzip(VectorSpecies<E> species, int part)	2つのベクトルの連結を解凍するシャッフルを作成します。代わりに、入力レーンを1つまたは他の出力ベクトルに格納します。
static <E> VectorShuffle<E>	makeZip(VectorSpecies<E> species, int part)	2つのベクトルをまとめて圧縮するシャッフルを作成します。代わりに、一方のベクトルからレーンを選択します。
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 - 種のboxed要素の型

パラメータ:

species - 目的のシャッフルの種

戻り値:

シェイプおよび要素型によって変換されたシャッフル

例外:

IllegalArgumentException - このシャッフルの長さと種の長さが異なる場合

check

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

このシャッフルが指定された種を持っていることを確認し、このシャッフルをそのまま返します。 効果は次の疑似コードのようになります : species == vectorSpecies() ? this : throw new ClassCastException()。

型パラメータ:

F - 必要な種のボックス化された要素型

パラメータ:

species - 必要な種

戻り値:

同じシャッフル

例外:

ClassCastException - シャッフル種が間違っている場合

関連項目:

• Vector.check(Class)
• Vector.check(VectorSpecies)

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が2の累乗であるかぎり、削減された索引もindex & (VLENGTH - 1)と等しくなります。

パラメータ:

index - レーンのインデックス

戻り値:

index。VLENGTHの適切な倍数によって[0..VLENGTH-1の範囲に調整されます

関連項目:

• VectorSpecies.loopBound(int)
• checkIndex(int)
• wrapIndexes()

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のthインデックス値が種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲内の例外インデックスに部分的にラップされます。

型パラメータ:

E - boxed要素型

パラメータ:

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 - boxed要素型

パラメータ:

species - シャッフル種

sourceIndexes - シャッフルの描画元のソース・インデックス

offset - 配列へのオフセット

戻り値:

各レーンのソース・インデックスが指定されたint値に設定されているシャッフル。例外の場合は部分的にラップされる

例外:

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]に適用される演算子の連続する値から、指定された種のシャッフルを作成します。

Nがシャッフル・レーンのインデックスであるシャッフル・レーンごとに、Nのthインデックス値が種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 - boxed要素型

パラメータ:

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はwrapがtrueの場合はwrapIndexで、それ以外の場合はアイデンティティ関数です。

wrapがfalseの場合、各索引は種VLENGTHに対して検証され、(無効な場合)は[-VLENGTH..-1]の範囲の例外的な索引に部分的にラップされます。 それ以外の場合、wrapがtrueであれば、wrapIndexによる場合と同様に、各索引を有効範囲[0..VLENGTH-1]に減らします。

APIのノート:

無効なソース索引をラップする場合は、wrapパラメータを trueに設定する必要があります。 それ以外の場合は、falseに設定すると、unary rearrangeなどの後続の演算で無効なソース索引を範囲チェックできます。

型パラメータ:

E - boxed要素型

パラメータ:

species - シャッフル種

start - ソース索引シーケンスの開始値

step - 隣接するソース索引間の差異

wrap - 結果の索引をラップするかどうか

戻り値:

シーケンシャル・レーン・インデックスのシャッフル(ラップされている可能性がある)

関連項目:

• VectorSpecies.iotaShuffle(int,int,boolean)

makeZip

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

2つのベクトルをまとめて圧縮するシャッフルを作成します。代わりに、一方のベクトルからレーンを選択します。 zipの論理結果はいずれかの入力のサイズの2倍であるため、「拡張された結果」は部品番号で選択された2つの物理的な部分に分割されます。 たとえば、[a,b,c,d]と[1,2,3,4]の両方のベクトルを圧縮すると、[a,1,b,2]と[c,3,d,4]の2つの部分で取得する必要がある拡張論理結果[a,1,b,2,c,3,d,4]が生成されます。

このメソッドは、Pがpart*VLENGTH/2である式VectorShuffle.fromOp(species, i -> i/2 + (i%2)*VLENGTH + Pの値を返します。

シャッフルの奇数レーン内のソース索引は、2番目のベクトルから選択する無効な索引(部分正規化後の>= VLENGTHまたは< 0)になることに注意してください。

型パラメータ:

E - boxed要素型

パラメータ:

species - シャッフルの種

part - 結果(ゼロまたは1つ)のパート番号

戻り値:

2つのベクトルを2*VLENGTHレーンに圧縮し、選択したパートを返すシャッフル

例外:

ArrayIndexOutOfBoundsException - partがゼロまたはいずれでもない場合

関連項目:

• makeUnzip(VectorSpecies, int)
• Vector.rearrange(VectorShuffle,Vector)

makeUnzip

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

2つのベクトルの連結を解凍するシャッフルを作成します。代わりに、入力レーンを1つまたは他の出力ベクトルに格納します。 解凍の論理結果はいずれかの入力のサイズの2倍であるため、「拡張された結果」は部品番号で選択された2つの物理的な部分に分割されます。 たとえば、2つのベクトル[a,1,b,2][c,3,d,4]を解凍すると、[a,b,c,d]と[1,2,3,4]の2つの部分に結果が生成されます。

このメソッドは、式VectorShuffle.fromOp(species, i -> i*2+partの値を返します。

シャッフルの上半分のソース索引は、もう一方のベクトルから選択する無効な索引(部分正規化後の>= VLENGTHまたは< 0)になります。

型パラメータ:

E - boxed要素型

パラメータ:

species - シャッフルの種

part - 結果(ゼロまたは1つ)のパート番号

戻り値:

2*VLENGTHレーンを2つのベクトルに解凍し、選択したパートを返すシャッフル

例外:

ArrayIndexOutOfBoundsException - partがゼロまたはいずれでもない場合

関連項目:

• makeZip(VectorSpecies,int)
• Vector.rearrange(VectorShuffle,Vector)

toArray

public abstract int[] toArray()

このシャッフルのレーンのソース・インデックスを含むint配列を返します。

このメソッドは、このシャッフルを割り当てられた配列(intoArrayを使用して)に格納するかのように動作し、その配列を次のように返します:

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

APIのノート:

シャッフル・ソース索引は、常に-VLENGTHからVLENGTH-1の範囲内にあります。 ソース索引は、負の場合にのみ例外です。

戻り値:

このシャッフルのレーンのソース・インデックスを含む配列

intoArray

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

このシャッフルをoffsetから始まるint配列に格納します。

シャッフル・レーンNごとに、そのレーン要素に格納されているレーンのソース索引が配列要素a[offset+N]に格納されます。

APIのノート:

シャッフル・ソース索引は、常に-VLENGTHからVLENGTH-1の範囲内にあります。

パラメータ:

a - int[]型の配列

offset - 配列へのオフセット

例外:

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のノート:

シャッフル・ソース索引は、常に-VLENGTHからVLENGTH-1の範囲内にあります。 これらの値は、浮動小数点型であっても、結果のベクトルのETYPEに変換されます。

戻り値:

このシャッフルのベクトル表現

laneSource

public int laneSource(int i)

レーン索引iのintレーン要素を取得

パラメータ:

i - レーンのインデックス

戻り値:

レーン索引iのintレーン要素

rearrange

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

別のシャッフルによって制御されているレーン・インデックスを選択して、このシャッフルのレーン要素を再配置します。

指定されたシャッフルのレーンごとに、レーン要素Iを含むレーン索引Nで、このシャッフルからIのレーン要素が選択され、Nの結果のシャッフルに配置されます。

パラメータ:

s - シャッフル・コント・ローリング・レーン索引の選択

戻り値:

このシャッフルのレーン要素の再配置

toString

public final String toString()

このシャッフルの文字列表現を"Shuffle[0,1,2...]"形式で返し、ソース・インデックスをレーン順に報告します。

オーバーライド:

toString、クラスObject

戻り値:

"Shuffle[0,1,2...]"形式の文字列

equals

public final boolean equals(Object obj)

このシャッフルが他のオブジェクトと同一かどうかを示します。 2つのシャッフルは、同じ種と同じソース・インデックスを同じ順序で持つ場合にのみ同一です。

オーバーライド:

equals、クラスObject

パラメータ:

obj - 比較対象の参照オブジェクト。

戻り値:

このベクトルがほかのオブジェクトと同一かどうか

関連項目:

• Object.hashCode()
• HashMap

hashCode

public final int hashCode()

レーンのソース・インデックスとベクトル種に基づいて、シャッフルのハッシュ・コード値を返します。

オーバーライド:

hashCode、クラスObject

戻り値:

このシャッフルのハッシュ・コード値

関連項目:

• Object.equals(java.lang.Object)
• System.identityHashCode(java.lang.Object)

getPayload

protected final Object getPayload()