VCSSL/Vnano プラグイン インターフェース 仕様書

Array Data Accessor Interface 1 (ADAI1)
インターフェース仕様書
(org.vcssl.connect.ArrayDataAccessorInterface1)


概要

Array Data Accessor Interface 1 (ADAI1) は、主に処理系のデータコンテナが実装してサポートする、データ入出力インターフェースの一つです。

この org.vcssl.connect パッケージ内では、スクリプトエンジン側とプラグイン側との間で、必要に応じてデータ型の変換なしにデータを受け渡しするための、 複数のデータ入出力インターフェースが提供されています。

その中でこの ADAI1 は、多次元配列データに対する入出力機能を提供します。

ステータス

このインターフェースの現在のステータスは "FINALIZED"(確定済み)です。

このインターフェースの仕様は、2022年8月31日時点で最終確定しました。今後は原則として、ドキュメントやコメント類以外の変更は加えられません。

現在は Vnano のスクリプトエンジンでサポートされ、同エンジンを搭載したアプリケーションのプラグイン開発において利用できます。

ライセンス

このインターフェースは、実質的な著作権フリー/パブリックドメインである CC0 に基づいて公開されています。

フィールド/メソッド等の一覧

型パラメータ
このインターフェースは、実装クラスのインスタンス生成時に、型パラメータ T の指定が必要です。
INTERFACE_TYPE_ID
プラグインのロード時に参照される、このインターフェースの形式ID(値: "ADAI")です。
INTERFACE_GENERATION
このインターフェースの世代名です(値: "1")。
ARRAY_SIZE_OF_SCALAR
スカラ値におけるサイズ値です(値: 1)。
ARRAY_RANK_OF_SCALAR
スカラ値における配列次元数(配列ランク値)です(値: 0)。
ARRAY_LENGTHS_OF_SCALAR
スカラ値における、各次元の長さを格納する配列です(値: { })。
void setArrayData(T data, int offset, int[] lengths)
1次元に直列化された配列データを、そのデータに関する必須情報と共に設定します。
T getArrayData()
1次元に直列化された配列データを取得します。
boolean hasArrayData()
1次元に直列化された配列データを取得可能かどうかを判定します。
int getArrayOffset()
1次元に直列化された配列データの中で、スカラ値が格納されているインデックスを返します。
int[] getArrayLengths()
配列データの各次元の長さを格納する配列を取得します。
int getArraySize()
1次元に直列化された直列化された配列としての、データのサイズ(長さ)を返します。
int getArrayRank()
配列データの次元数(配列ランク値)を返します。

型パラメータ

このインターフェースの実装クラスは、以下のように、インスタンス生成の際に型パラメータを指定します:

ArrayDataAccessorInterface1<double[]> instance = new ImplClass<double[]>();

ここでImplClassクラスは、このインターフェースを実装したクラスの例です。 上記で指定している double[] が型パラメータで、本ドキュメント内では「 T 」と表します。

フィールド

名前 INTERFACE_TYPE_ID
値の意味 プラグインのロード時に参照される、このインターフェースの形式ID(値: "ADAI")です。
データ型 static final String
名前 INTERFACE_GENERATION
値の意味 このインターフェースの世代名です(値: "1")。
データ型 static final String
名前 ARRAY_SIZE_OF_SCALAR
値の意味 スカラ値におけるサイズ値です(値: 1)。
データ型 static final int
名前 ARRAY_RANK_OF_SCALAR
値の意味 スカラ値における配列次元数(配列ランク値)です(値: 0)。
データ型 static final int
名前 ARRAY_LENGTHS_OF_SCALAR
値の意味 スカラ値における、各次元の長さを格納する配列です(値: { })。
データ型 static final int[ ]

メソッド

名前 setArrayData
宣言形式 void setArrayData(T data, int offset, int[] lengths)
機能

1次元に直列化された配列データを、そのデータに関する必須情報と共に設定します。

このインターフェースでは、スカラ値や多次元配列も含めて、データは全て1次元の配列として入出力します。 そのため、引数 data には常に 1 次元配列を渡してください。1 次元配列への、データの格納の仕方は下記の通りです。

スカラ値を設定する場合: 引数 data には、スカラ値が要素として、任意のインデックスの位置に格納されている配列を1次元指定します。 そして、そのインデックスを引数 offset に指定します。 引数 lengths には、長さ 0 のから配列を指定します (即ち、このインターフェースではスカラ値を「 0 次元の配列 」と見なして扱います)。

1次元配列データを設定する場合: 引数 data には、設定したい1次元配列データをそのまま指定します。 引数 offset には、常に 0 を指定します。 引数 lengths には、長さが 1 で、[0] の位置に1次元配列データ(引数 data に指定)の長さが格納された配列を指定します。

多次元配列データを格納する場合: 引数 data には、多次元配列の各要素値を、下記の通り規則的に並べた(直列化された) 1 次元配列を指定します:

(長さが [N1][N2] の 2 次元配列の場合)
data[ 直列化されたインデックス ] = 2次元配列[ 1次元目のインデックス ][ 2次元目のインデックス ]
ここで「直列化されたインデックス」は以下のように求めます:
直列化されたインデックス = N2 * 1次元目のインデックス + 2次元目のインデックス
(長さが [N1][N2][N3] の 3 次元配列の場合)
data[ 直列化されたインデックス ] = 3次元配列[ 1次元目のインデックス ][ 2次元目のインデックス ][ 3次元目のインデックス ]
ここで「直列化されたインデックス」は以下のように求めます:
直列化されたインデックス = N3*N2 * 1次元目のインデックス + N3 * 2次元目のインデックス + 3次元目のインデックス
(長さが [N1][N2][N3][N4] の 4 次元配列の場合)
data[ 直列化されたインデックス ] = 4次元配列[ 1次元目のインデックス ][ 2次元目のインデックス ][ 3次元目のインデックス ][ 4次元目のインデックス ]
ここで「直列化されたインデックス」は以下のように求めます:
直列化されたインデックス = N4*N3*N2 * 1次元目のインデックス + N4*N3 * 2次元目のインデックス + N4 * 3次元目のインデックス + 4次元目のインデックス
...

引数 offset には、常に 0 を指定します。 引数 lengths には、長さが多次元配列データ(引数 data に指定)の次元数に等しい配列を指定し、 その中に、各次元の長さを格納します。その際、要素 [0] が左端次元の長さを表し、要素 [max] が右端次元の長さを表します (具体例としては、長さ [N1][N2][N3] の 3 次元配列においては {N1, N2, N3} を指定します)。

なお、data や offset および lengths の値を個別に設定するメソッドは、 それらの関係が瞬間的にでも不整合な状態になる事を防ぐため、提供されません。

引数 data: 設定するデータ(上記参照)
offset: スカラ値の格納位置(上記参照)
lengths: 次元ごとの長さを格納する配列
戻り値 なし
名前 getArrayData
宣言形式 T getArrayData()
機能 1次元に直列化された配列データを取得します。
スカラ値や多次元配列データの格納のされ方については、 setArrayData メソッドの説明を参照してください。
引数 なし
戻り値 データ内容を格納する(直列化された) 1 次元配列
名前 hasArrayData
宣言形式 boolean hasArrayData()
機能 1次元に直列化された配列データを取得可能かどうかを判定します。
引数 なし
戻り値 配列データを取得可能であれば true が返されます。
名前 getArrayOffset
宣言形式 int getArrayOffset()
機能 1次元に直列化された配列データの中で、スカラ値が格納されているインデックスを返します。 詳細は、 setArrayData メソッドの引数 offset に関する説明を参照してください。
引数 なし
戻り値 配列データの中で、スカラ値が格納されているインデックス
名前 getArrayLengths
宣言形式 int[] getArrayLengths()
機能 配列データの各次元の長さを格納する配列を取得します。 詳細は、 setArrayData メソッドの引数 lengths に関する説明を参照してください。
引数 なし
戻り値 配列データの各次元の長さを格納する配列
名前 getArraySize
宣言形式 int getArraySize()
機能 1次元に直列化された配列としての、データのサイズ(長さ)を返します。
データがスカラ値の場合、サイズは常に 1 となります。
データが 1 次元配列の場合、サイズはその長さそのものです。
データが長さ [N1][N2][N3]...[NM] の多次元配列の場合、サイズは N1*n2*n3*...*NM となります。
引数 なし
戻り値 直列化された 1 次元配列としてのデータのサイズ(長さ)
名前 getArrayRank
宣言形式 int getArrayRank()
機能 配列データの次元数(配列ランク値)を返します。
データがスカラ値の場合、配列ランク値は常に 0 となります。
データが 1 次元配列の場合、配列ランク値は常に 1 となります。
データが N 次元配列の場合、配列ランク値は N です。
引数 なし
戻り値 多次元配列データの次元数(配列ランク値)