Array of 1 type of object (ARRY)


Functions

bool isARRAY (SatAddr src)
 is the object at src an ARRAY object?
int ARRAYnibbles (SatAddr src)
 Return the number of nibbles in a ARRAY object.
SatAddr makeARRAY (SatAddr element, int numDimensions, int dim1,...)
 Create an N-dimensional array.
SatAddr ARRAYgetItem (SatAddr array, SatAddr dst, int idx1,...)
 Get a copy of an item in an array.
int ARRAYputItem (SatAddr array, SatAddr item, int idx1,...)
 Put an item into an array.
SatAddr ARRAYfirstItem (SatAddr array, SatAddr dst, SatAddr *iter)
 Get the first item in an array.
SatAddr ARRAYnextItem (SatAddr array, SatAddr dst, SatAddr *iter)
 Return the next item in an array.
int ARRAYnumDimensions (SatAddr array)
 Return the number of dimensions in an array.
int ARRAYgetDimension (SatAddr array, int dimensionNumber)
 Get the size of the i'th dimension.
int ARRAYgetElProlog (SatAddr array)
 get the prolog value of the items stored in the array.
int ARRAYgetElementBody (SatAddr array, SatAddr *elementBody, int idx1,...)
 Get the Saturn address of an element body in an array.
int ARRAYelementSize (SatAddr array, SatAddr element)
 Get the size of an element body in an array.
SatAddr ARRAYfirstElement (SatAddr array)
 Get the first element body in an array.
SatAddr ARRAYnextElement (SatAddr array, SatAddr prev)
 Return the next element body in an array.

Detailed Description

Array's store many objects of a single type by storing one copy of the prolog and then storing each object's body without its prolog. Thus to access an object within the array, we need to copy the prolog and body somewhere else. Functions are provided to do this.

For lower level access, functions are also provided to access the object bodies directly.

Warning:
Note that in the C routines, array indexes start at zero. Also, note that dimension numbers start at zero.

Function Documentation

int ARRAYelementSize ( SatAddr  array,
SatAddr  element 
)

Get the size of an element body in an array.

Given an array and a pointer to an element body in an array, return the size of the element in the array. Since the array contains the body of an object, the size needed to reconstitute this object is 5+ARRAYelementSize().

Parameters:
array The ARRAY object
element The element body
Returns:
The element's size, or -1 on error.
See also:
ARRAYgetElementBody(), ARRAYfirstElement(), ARRAYnextElement()

SatAddr ARRAYfirstElement ( SatAddr  array  ) 

Get the first element body in an array.

Parameters:
array The ARRAY object
Returns:
The Saturn address of the first element body in the array, or zero on error or if no elements are in the array.
Warning:
Note that there is no way to distinguish between an empty array and an error. If in doubt, use ISARRAY() to make sure it is an ARRAY object first.

SatAddr ARRAYfirstItem ( SatAddr  array,
SatAddr  dst,
SatAddr iter 
)

Get the first item in an array.

Parameters:
array The ARRAY object
dst If non-null, then the array item, including its prolog will be copied here. Otherwise space will be allocated in TEMPOb for the item and it will be copied there.
iter A pointer to a SatAddr variable. This will be set to a value that can be passed to ARRAYnextItem() to get the next item.
Returns:
The Saturn address of the item, or zero on error

int ARRAYgetDimension ( SatAddr  array,
int  dimensionNumber 
)

Get the size of the i'th dimension.

Dimensions are numbered from zero, so valid dimensions are 0, 1, 2, 3, etc).

Parameters:
array The ARRAY object
dimensionNumber The dimension number (0, 1, 2, etc)
Returns:
The size of the dimension, or -1 on error
For example, if arr is a 2x4 array, then ARRAYgetDimension(arr,0) return 2 and ARRAYgetDimension(arr,1) return 4.

int ARRAYgetElementBody ( SatAddr  array,
SatAddr elementBody,
int  idx1,
  ... 
)

Get the Saturn address of an element body in an array.

Arrays store object bodies, without their prologs. This function gets the address of one such body.

Parameters:
array The ARRAY object
elementBody Address of a SatAddr variable. The Saturn address of the element's body will be stored here.
idx1 Index value of the array's first dimension. NOTE! In keeping with C conventions, the index values start at zero, not 1!!
idxN Index value of the n'th index. You must pass as many indices as there are dimensions.
Returns:
Returns zero on success. Returns -3 if "array" isn't an ARRAY. Returns -10-n if the n'th index value is out of range.
See also:
ARRAYgetElement() to get an actual HP Object constructed from the body and prolog.

int ARRAYgetElProlog ( SatAddr  array  ) 

get the prolog value of the items stored in the array.

Parameters:
array The ARRAY object
Returns:
the Prolog value or -1 on error.

SatAddr ARRAYgetItem ( SatAddr  array,
SatAddr  dst,
int  idx1,
  ... 
)

Get a copy of an item in an array.

Parameters:
array The ARRAY object
dst If non-null, then the array item, including its prolog will be copied here. Otherwise space will be allocated in TEMPOb for the item and the it will be copied there.
idx1 Index value of the array's first dimension. NOTE! In keeping with C conventions, the index values start at zero, not 1!!
idxN Index values for the rest of the dimensions. You must pass as many indices as there are dimensions.
Returns:
The Saturn address of the item, or zero on error
To avoid filling up TempOb, you should pass a non-null value to dst if at all possible.

Because arrays store object bodies separate from object prologs, we must copy the object and prolog to a separate place to have meaningful access to it.

This function's speed depends on greatly on whether the array contains fixed-sized objects. If the objects are all the same size (like REAL numbers), then it uses arithemetic to compute the address of the appropriate item. Otherwise the funtion is forced to scan through the array to find the right one.

SatAddr ARRAYnextElement ( SatAddr  array,
SatAddr  prev 
)

Return the next element body in an array.

Returns:
The Saturn address of the next element body following "prev" in the array, or zero if no more elements are present, or if an error occurs.

SatAddr ARRAYnextItem ( SatAddr  array,
SatAddr  dst,
SatAddr iter 
)

Return the next item in an array.

Parameters:
array The ARRAY object
dst If non-null, then the array item's prolog and body will be copied here. Otherwise space will be allocated in TEMPOb for the item and it will be copied there.
iter A pointer to a SatAddr variable that was previously passed to ARRAYfirstItem() or ARRAYnextItem(). This will be updated to a value that can be passed to ARRAYnextItem() again to get the following item.
Returns:
The Saturn address of the next item in the array, or zero if no more items are available, or if an error occurs. In addition, *iter is updated.

int ARRAYnibbles ( SatAddr  src  ) 

Return the number of nibbles in a ARRAY object.

Parameters:
src Saturn address of a ARRAY object.
Returns:
The size of the ARRAY

int ARRAYnumDimensions ( SatAddr  array  ) 

Return the number of dimensions in an array.

Parameters:
array The ARRAY object
Returns:
The number of dimensions, or -1 on error.

int ARRAYputItem ( SatAddr  array,
SatAddr  item,
int  idx1,
  ... 
)

Put an item into an array.

Parameters:
array The ARRAY object
item The item to copy into the array.
idx1 Index value of the array's first dimension. NOTE! In keeping with C conventions, the index values start at zero, not 1!!
idxN Index values for the rest of the dimensions. You must pass as many indices as there are dimensions.
Returns:
Returns 0 on success. Returns -1 if "item" is not the same type as the objects in the array. Returns -2 if "item" is not the size as the item that it is replacing. Returns -3 if "array" isn't an ARRAY object. Returns -10-n if the n-th index is out of range.

bool isARRAY ( SatAddr  src  ) 

is the object at src an ARRAY object?

Parameters:
src Saturn address of an object
Returns:
true if the object at src is an ARRAY object.

SatAddr makeARRAY ( SatAddr  element,
int  numDimensions,
int  dim1,
  ... 
)

Create an N-dimensional array.

Example: make a 4x5 array of real numbers. Initialize each value with 1.0

SatAddr myArray = makeARRAY(REALencode(1.0, 0), 2, 4, 5);

Example: make a 1-dimensional array of 10 lists where each list is { 1. 2. 3. }

SatAddr theList = LISTencode(0, REALencode(1., 0), REALencode(2., 0), REALencode(3.,0), 0));
SatAddr myArray = makeARRAY(theList, 1, 10);


Generated on Sat Apr 3 16:38:31 2010 for HPObjects by  doxygen 1.5.0