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 です。
引数 | なし
戻り値 | 多次元配列データの次元数（配列ランク値）