VCSSL/VNANO PLUGIN INTERFACE SPECIFICATION

# Array Data Accessor Interface 1 (ADAI1)
Specification Document
(org.vcssl.connect.ArrayDataAccessorInterface1)

## Abstract

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.

## Status

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.

## License

This interface is published under CC0, which is almost the same as the so-called "copyright-free" (domain).

## List of Fields/Methods

Type Parameter
  This interface has a type parameter T, which should be specified when instantiate a class implementing this interface.
INTERFACE_TYPE_ID
  The type ID of this interface (value: "ADAI") referred when the plug-in will be loaded.
INTERFACE_GENERATION
  The generation of this interface (value: "1").
ARRAY_SIZE_OF_SCALAR
  The value of size of a scalar value (value: 1).
ARRAY_RANK_OF_SCALAR
  The number of dimensions (array-rank) of a scalar value (value: 0).
ARRAY_LENGTHS_OF_SCALAR
  An array storing dimension-lengths of a scalar value (value: { }),
void setArrayData(T data, int offset, int[] lengths)
  Sets the serialized 1D array data with related information.
T getArrayData()
  Returns the serialized 1D array data.
boolean hasArrayData()
  Returns whether any serialized 1D array data can be gotten
int getArrayOffset()
  Returns the index of the scalar value in the serialized 1D array data.
int[] getArrayLengths()
  Returns the array storing lengths of dimensions of the array.
int getArraySize()
  Returns the size (lenth) of the serialized 1D array data.
int getArrayRank()
  Returns the number of dimensions (array-rank) of the array.

## Type Parameter

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".

## Fields

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[ ]

## Methods

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.