Array Data Accessor Interface 1 (ADAI1) is a data-I/O interface, mainly implemented by data container objects of language processor systems.
In this org.vcssl.connect package, multiple data I/O interfaces are provided for passing/receiving data without any data-conversions, between script-engine-side and plug-in-side, if required.
In them, this interface ADAI1 provides I/O methods of multi-dimensional array data.
The status of this interface is "FINALIZED".
The specification of this interface had been finalized at 2022/08/31. No modifications will be applied for this interface, excluding documents/comments.
This interface is currently supported by the scripting engine of Vnano. You can use this interface for development of plug-ins of applications equipped with the Vnano engine.
This interface is published under CC0, which is almost the same as the so-called "copyright-free" (domain).
This interface has a type parameter T, which should be specified when instantiate a class implementing this interface, as follows:
ArrayDataAccessorInterface1<double[]> instance = new ImplClass<double[]>();
Whete "ImplClass" implements this ADAI 1 interface. In the above, "double[]" is the type parameter.
In this document, we describe the type parameter as "T".
| Name | INTERFACE_TYPE_ID |
|---|---|
| Value | The type ID of this interface (value: "ADAI") referred when the plug-in will be loaded. |
| Type | static final String |
| Name | INTERFACE_GENERATION |
|---|---|
| Value | The generation of this interface (value: "1"). |
| Type | static final String |
| Name | ARRAY_SIZE_OF_SCALAR |
|---|---|
| Value | The value of the size of a scalar value (value: 1). |
| Type | static final int |
| Name | ARRAY_RANK_OF_SCALAR |
|---|---|
| Value | The number of dimensions (array-rank) of a scalar value (value: 0). |
| Type | static final int |
| Name | ARRAY_LENGTHS_OF_SCALAR |
|---|---|
| Value | An array storing dimension-lengths of a scalar value (value: { }). |
| Type | static final int[ ] |
| Name | setArrayData |
|---|---|
| Signature | void setArrayData(T data, int offset, int[] lengths) |
| Description |
Sets the serialized 1D array data with related information. On this interface, contents of any data including a scalar value, an 1-dimensional (1D) array, and a multi-dimensional array are always handled as an 1D array, so specify an 1D array for the argument "data". We call it as "serialized 1D array data" in this document. When set a scalar value: For the argument "data", specify an 1D array in which the scalar value is stored as an element, at any index. In addition, specify the array-index of the stored scalar value to the argument "offset". For the argument "lengths", specify an empty array of which length is 0 (so we regard an scalar value as a "0-dimensional array" on this interface). When set 1-dimensional array data: For the argument "data", specify the 1-D array data as it is. For the argument "offset", always specify 0. For the argument "lengths", specify an array of which length is 1, and stores the length of array data (specified to the argument "data") at [0]. When set multi-dimensional array data: For the argument "data", specify the serialized 1D array in which data of multi-dimensional array is aligned in the form of:
(The case of 2D array: multiDimArray[N1][N2])
data[ index1D ] = multiDimArray[ multiIndex1 ][ multiIndex2 ] Where "index1D" is determined as follows: index1D = N2*multiIndex1 + multiIndex3
(The case of 3D array: multiDimArray[N1][N2][N3])
data[ index1D ] = multiDimArray[ multiIndex1 ][ multiIndex2 ][ multiIndex3 ] Where "index1D" is determined as follows: index1D = N3*N2*multiIndex1 + N3*multiIndex2 + multiIndex3
(The case of 4D array: multiDimArray[N1][N2][N3][N4])
...
data[ index1D ] = multiDimArray[ multiIndex1 ][ multiIndex2 ][ multiIndex3 ][ multiIndex4 ] Where "index1D" is determined as follows: index1D = N4*N3*N2*multiIndex1 + N4*N3*multiIndex2 + N4*multiIndex3 + multiIndex4 For the argument "offset", always specify 0. For the argument "lengths", specify an array of which length equals to the number of dimensions of the serialized 1D data array, and stores lengths of each dimension, where [0] represents the length of most-left dimension, and [max] represents the length of most-right dimension (so specify {N1, N2, N3} for 3D array data of which lengths are [N1][N2][N3]). By the way, methods for setting a value "data", "offset", or "lengths" independently are not provided, for preventing inconsistency between them (never allowed even for a moment). |
| Parameters |
data: The serialized 1D array data to be set (see the above explanation).
offset: The index at with the scalar value is stored. lengths: An array storing lengths of each dimension (see the above explanation). |
| Return | None |
| Name | getArrayData |
|---|---|
| Signature | T getArrayData() |
| Description |
Returns the serialized 1D the array data.
How a scalar or a multi dimensional array is stored in the serialized 1D array data is explained in the section of setArrayData method. |
| Parameters | None |
| Return | The serialized 1D array data. |
| Name | hasArrayData |
|---|---|
| Signature | boolean hasArrayData() |
| Description | Returns whether any serialized 1D array data can be gotten. |
| Parameters | None |
| Return | Returns true if any serialized 1D array data can be gotton. |
| Name | getArrayOffset |
|---|---|
| Signature | int getArrayOffset() |
| Description | Returns the index of the scalar value in the serialized 1D array data. For details, see the description of setArrayData method. |
| Parameters | None |
| Return | The index of the scalar value in the serialized 1D array data. |
| Name | getArrayLengths |
|---|---|
| Signature | int[] getArrayLengths() |
| Description | Returns the array storing lengths of dimensions of the array. For details, see the description of setArrayData method. |
| Parameters | None |
| Return | The array storing lengths of dimensions of the array. |
| Name | getArraySize |
|---|---|
| Signature | int getArraySize() |
| Description |
Returns the size (lenth) of the serialized 1D array data.
When data is a scalar value, the size always is 1. When data is an 1-dimensional array, the size is its length. When data is a multi-dimensional array of which lengths are [N1][N2][N3]...[NM], the size is the value of the product of them: N1*n2*n3*...*NM. |
| Parameters | None |
| Return | The size (lenth) of the serialized 1D array data. |
| Name | getArrayRank |
|---|---|
| Signature | int getArrayRank() |
| Description |
Returns the number of dimensions (array-rank) of the array.
When data is a scalar value, the array-rank always is 0. When data is an 1-dimensional array, the array-rank always is 1. When data is an N-dimensional array, the array-rank is N. |
| Parameters | None |
| Return | The number of dimensions (array-rank) of multi-dimensional array data. |