STAB_GetElem

The STAB_GetElem function returns a string stored at a specific index in a STAB object.

extern STAB_GetElem
  float handle         // handle to STAB
  float index          // index to data
  stringvar strdata$   // string variable to receive string
  floatvar fltdata     // (optional) float variable to receive associated data

Parameters

handle

[in] Handle to a STAB object previously returned from STAB_Create.

index

[in] The zero-based index of the string to retrieve.

strdata$

[out] The string variable that will be set with the string stored in the STAB object specified by handle and index.

fltdata

[out] The float variable that will be set with the optional data associated with the string when it was added to the STAB object.

Remarks

If handle is not a valid STAB handle, an error message will be printed to the console. If index is not at least zero and strictly less than the value returned from STAB_GetSize, an error message will be printed to the console. For example, if the array size is 10, then the possible values of index is between 0 and 9.

If there was no optional float value specified when the string was added to the STAB object, fltdata will have a value of zero.

Example

The following code fragment demonstrates how to use a loop to retrieve every element in a STAB object.

// Assume @handle is already initialized to
// a STAB object with data in it.

extern STAB_GetSize @handle @size

@i = 0
while (@i < @size)
{
    STAB_GetElem @handle @i @str$
    // Do something useful with the string.
}