Plugin SDK Array Reference

From Real Software Documentation

Contents 1 REALCreateArray 2 REALGetArrayUBound 3 REALGetArrayStructure 4 REALGetArrayValue@Type@ 5 REALSetArrayValue@Type@ 6 REALInsertArrayValue@Type@

REALCreateArray

Creates a single-dimensional array based on the given type and bounds. Note that you cannot create multi-dimensional arrays from a plugin. Also, a REALbasic array is not the same thing as a C array, so you cannot make any assumptions about the return value aside from it being an opaque datatype.

REALarray REALCreateArray( REALArrayType type, long bounds )

• type: the element type of the array. Possible values are:
  • kTypeFloat32 = 1, // 32-bit float type (single)
  • kTypeFloat64 = 2, // 64-bit float type (double)
  • kTypeString = 3, // string (32 bit pointer, refcounted)
  • kTypeObject = 4, // object (32 bit pointer, refcounted)
  • kTypeUInt8 = 5, // 8-bit unsigned integer, or boolean
  • kTypeSInt8 = 6, // 8-bit signed integer
  • kTypeUInt16 = 7, // 16-bit unsigned integer
  • kTypeSInt16 = 8, // 16-bit signed integer
  • kTypeUInt32 = 9, // 32-bit unsigned integer
  • kTypeSInt32 = 0, // 32-bit integer, or color
  • kTypeUInt64 = 10, // 64-bit unsigned integer
  • kTypeSInt64 = 11, // 64-bit signed integer, or Currency
• bounds: the zero-based upper-bounds of the array. Can be -1 for an empty array.

Return Value The newly created array object.

REALGetArrayUBound

Returns the zero-based upper-bound of the array passed in.

int REALGetArrayUBound(void *array);

• array: the array object to query. While the type of the parameter is void *, that is a historical fact which remains for backwards compatibility. You should always pass a REALarray.

Return Value The upper-bounds of the array. If the array is empty, the return value will be -1.

REALGetArrayStructure

Retrieves a structure from the given array at the index given. The array internally knows the size of the structure elements it holds. Because of this, the array will copy the structure information into the given buffer. Use caution when passing in the buffer; the size of the buffer must be large enough for the array to copy the structure as the array does not check buffer sizes.

void REALGetArrayStructure( REALarray array, int index, void *structure )

• array: the array object to retrieve a structure from
• index: the zero-based index of the element to retrieve
• structure: the buffer to copy the structure data into

Return Value None.

REALGetArrayValue@Type@

Retrieves data from the given array at the index given. There is one version of REALGetArrayValue for each of the following REALbasic datatypes: Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8, Single, Double, Boolean, Object and String. If the array holds colors, then you should use the Int32 version of this API. If the array holds currency values, then you should use the Int64 version of this API. Note that arrays can throw an OutOfBoundsException if the index is out of bounds. However, plugins cannot catch REALbasic exceptions, so be certain to verify the index is in bounds before calling this function. The "flat C" version of the plugins SDK has one function for each datatype to get the array value. However, unless you need to use the "flat C" version of the SDK, you can simply use the REALGetArrayValue macro instead of differentiating based on type.

void REALGetArrayValue@Type@( REALarray arr, long index, @Type@ *value );

• arr: the array object to retrieve the data from
• index: the zero-based index of the element to retrieve
• value: a properly-typed pointer to store the element data into

Return Value None.

REALSetArrayValue@Type@

Assigns data from value into the array at the index given. There is one version of REALSetArrayValue for each of the following REALbasic datatypes: Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8, Single, Double, Boolean, Object and String. If the array holds colors, then you should use the Int32 version of this API. If the array holds currency values, then you should use the Int64 version of this API. Note that arrays can throw an OutOfBoundsException if the index is out of bounds. However, plugins cannot catch REALbasic exceptions, so be certain to verify the index is in bounds before calling this function. The "flat C" version of the plugins SDK has one function for each datatype to set the array value. However, unless you need to use the "flat C" version of the SDK, you can simply use the REALSetArrayValue macro instead of differentiating based on type.

void REALSetArrayValue@Type@( REALarray arr, long index, @Type@ value );

• arr: the array object to assign data into
• index: the zero-based index of the element to assign
• value: a properly typed value to store into the array

Return Value None.

REALInsertArrayValue@Type@

Inserts data from value into the array at the given index. There is one version of REALInsertArrayValue for each of the following REALbasic datatypes: Int64, Int32, Int16, Int8, UInt64, UInt32, UInt16, UInt8, Single, Double, Boolean, Object and String. If the array holds colors, then you should use the Int32 version of this API. If the array holds currency values, then you should use the Int64 version of this API. Note that arrays can throw an OutOfBoundsException if the index is out of bounds. However, plugins cannot catch REALbasic exceptions, so be certain to verify the index is in bounds before calling this function. The "flat C" version of the plugins SDK has one function for each datatype to insert the value into the array. However, unless you need to use the "flat C" version of the SDK, you can simply use the REALInsertArrayValue macro instead of differentiating based on type.

void REALInsertArrayValue@Type@( REALarray arr, long index, @Type@ value );

• arr: the array object to insert data into
• index: the zero-based index of the position to insert the element at
• value: a properly typed value to store into the array

Return Value None.

This function crashes if the array object is nil. So check for this before you insert.