Arrays

As discussed in Section 5.4, SIDL supports both normal and raw arrays (i.e., r-arrays). Normal SIDL arrays can be used by any supported language; whereas, r-arrays are restricted to numeric types. This subsection discusses both within the context of Java bindings.

Every object and type defined in SIDL has a corresponding array to hold elements of that type. In the case of Java bindings, this means the entire SIDL array API is available with a few exceptions that have no real use in the language. More specifically, ensure(), borrow(), and first() are not supported in the bindings. Unlike with most of the other language bindings, explicit array deletion should be done using the destroy() array function. Refer to Subsection 5.4 for more information on the API.

More to the point are the specifics of the Java implementation -- which provides a wider variety of options for constructing arrays than other bindings. Each SIDL type and class includes a static inner class named Array. This is the main Array class and, in order to support up to 7 dimensional arrays, every method takes either 7 array indices or an array of indices. For example, in order to get the element (2,3) from a 2 dimensional array, arry._get(2,3,0,0,0,0,0) would be used. Since typing all those zeros can get a little tedious, a set of array subclasses have also been implemented with one subclass per supported dimension. So, given an Array2 instead of an Array, arry2._get(2,3) could be used to get the element (2,3) instead.

These numbered array subclasses improve on the array API usability somewhat, but they do have a side effect. In order to avoid conflicts between the array superclass and the numbered array subclass functions, all other basic array methods found in the Array superclass are preceded by an underscore '_'. For example, arry._dim() returns an array's dimensionality. Since numbered arrays all inherit these methods, they can be used as well. In the dimensionality example, arry2._dim() could also be used -- though the answer should be obvious.

Furthermore, there is another underscore rule for arrays in Java. All numbered arrays have two get and two set functions. The _get and _set functions are the same in Array and all the Array# subclasses in that they simply pass the arguments of the _get call down to the underlying implementation. However, the underscore-less get and set methods do bounds checking in Java before calling the underlying implementation. If a problem is detected, they throw ArrayIndexOutOfBoundsException.

Because numbered arrays are subclasses of Array, an Array# can be Java cast to an Array, if necessary. However, some functions return an Array. In order to convert an Array to the correctly numbered array, a function in Array, called _dcast(), can be used by simply invoking _dcast() on the object. For example, given a one-dimensional array of type foo.bar called arry that is represented by the Java class Array, the correctly numbered array type can be retrieved as follows$:$


foo.bar.Array1 arry1 = arry._dcast();

After this cast, two references are now available to the same array; namely, arry and arry1.

Finally, the Java array constructors are slightly different than in other languages. The constructor definition for Array is$:$


public Array(int dim, int[] lower, int[] upper, boolean isRow) 

This constructor creates an array of dimension dim. It takes two arrays of integers to define the lower and upper bounds of each dimension in the array. If lower or upper has fewer elements than there are dimensions in the array, or any element in lower is larger than the corresponding element in upper, the constructor will throw an exception. Finally, the constructor takes a boolean isRow. If isRow is true, a SIDL array will be created in row-major order; if false, a column-major order array will be created.

Constructors for numbered arrays are simpler. The constructor for a two-dimensional array is$:$


public Array2( int l0, int l1, int u0, int u1, boolean isRow)

Since the dimensionality is known, the dimension argument was dropped. In addition, it is no longer necessary to create arrays of bounds to pass into the constructor; instead, l0 and l1 are the lower bounds and u0 and u1 the upper. The choice between column- and row-major orders is obviously still necessary.

For arrays with all lower bounds of zero, an even simpler constructor is available. Its signature is$:$


public Array2( int s0, int s1, boolean isRow) 

Another alternate construction method for SIDL arrays is present in numbered arrays. The following constructor takes a two-dimensional Java array, and copies it into a 2-dimensional SIDL array:


public Array2(foo.bar[][] array, boolean isRow)

Alternatively, arrays can be constructed as copies of existing arrays through two additional built-in methods. An existing numbered SIDL array of the correct dimension can be set to the same contents of a Java array with the fromArray method. The same arguments as the constructor above are used but nothing is returned. Conversely, a SIDL array can be copied into a Java array through the toArray numbered array function. The function takes no arguments but returns a new Java array containing copies of the SIDL array's elements.



babel-1.4.0
users_guide Last Modified 2008-10-16

http://www.llnl.gov/CASC/components
components@llnl.gov