The Array API

In the following presentation, we use the SIDL double type; however, everything in this section applies to all types except where noted. The basic types are in the SIDL namespace. Table 5.2 shows the prefix for SIDL base types and the actual value type held by the array...


Table 5.2: SIDL types to array function prefixes
SIDL TYPE ARRAY FUNCTION PREFIX VALUE TYPE
bool sidl_bool sidl_bool
char sidl_char char
dcomplex sidl_dcomplex struct sidl_dcomplex
double sidl_double double
fcomplex sidl_fcomplex struct sidl_fcomplex
float sidl_float float
int sidl_int int32_t
long sidl_long int64_t
opaque sidl_opaque void *
string sidl_string char *

For arrays of interfaces or classes, the name of the array function prefix is derived from the fully qualified type name. For example, for the type sidl.BaseClass, the array functions all begin with sidl_BaseClass. For sidl.BaseInterface, they all begin with sidl_BaseInterface.

When you add an object or interface to an array, the reference count of the element being overwritten is decremented, and the reference count of the element being added is incremented. When you get an object or interface from an array, the caller owns the returned reference.

For arrays of strings when you add a string to any array, the array will store a copy of the string. When you retrieve a string from an array, you will receive a copy of the string. You should sidl_String_free the returned string when you are done with it.

When you create an array of interfaces, classes, or strings, all elements of the array are initialized to NULL. Other arrays are not initialized. When an array of interfaces, classes, or strings is destroyed, it releases any held references in the case of objects or interfaces. In the case of strings, it frees any non-NULL pointers.

The name of the data structure that holds the array if double is struct sidl_double__array. For some types, the data structure is an opaque type, and for others, it is defined in a public C header file.


Table 5.3: SIDL Array Functions
SHORT NAME DESCRIPTION
createCol Creates a column-major order SIDL array
createRow Creates a row-major order SIDL array
create1d Creates a dense one-dimensional SIDL array
create2dCol Creates a dense, column-major, two-dimensional SIDL array
create2dRow Creates a dense, column-major, two-dimensional SIDL array
slice Creates a sub-array of another array. Takes parameters to define array properties.
borrow Makes a SIDL array from thrid party data without copying it
smartCopy Copies a borrowed array or addRefs a non-borrowed array
addRef Increments the reference count.
deleteRef Decrements the reference count.
get1 Returns the indexed element from a one-dimensional array
get2 Returns the indexed element from a two-dimensional array
get3 Returns the indexed element from a three-dimensional array
get4 Returns the indexed element from a four-dimensional array
get5 Returns the indexed element from a five-dimensional array
get6 Returns the indexed element from a six-dimensional array
get7 Returns the indexed element from a seven-dimensional array
get Returns the indexed element from an array of any dimension
set1 Sets the indexed element in a one-dimensional array
set2 Sets the indexed element in a two-dimensional array
set3 Sets the indexed element in a three-dimensional array
set4 Sets the indexed element in a four-dimensional array
set5 Sets the indexed element in a five-dimensional array
set6 Sets the indexed element in a six-dimensional array
set7 Sets the indexed element in a seven-dimensional array
set Sets the indexed element in an array of any dimension
dimen Returns the dimension of the array
lower Returns the lower bound of the specified dimension
upper Returns the upper bound of the specified dimension
stride Returns the stride of the specified dimension
length Returns the length of the Array in the specified dimension
isColumnOrder Returns true if the array is a dense column-major order array, false otherwise
isRowOrder Returns true if the array is a dense row-major order array, false otherwise
copy Copies the contents of source array to dest array
ensure Returns an array with guaranteed ordering and dimension from any array.
first Provides direct access to the element data of the array.

The functions are listed succinctly in Table 5.3 as well as in detail over the next few pages.



Subsections


babel-0.10.2
users_guide Last Modified 2005-03-23

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