STAB Overview

String tables have been a frequently-requested feature in APE, and now they are available through a set of externs. STAB stands for String TABle, and the interface generally relies upon the usage of a STAB handle returned from a call to STAB_Create.

Once this handle is obtained, the ape script can begin to add items to the list by using STAB_Append. Optionally, each string can also have an associated float value which is set at the time that the string is added to the table.

When the script is finished using the STAB object, it should call STAB_Destroy. A STAB object which remains in use for the entire duration of the level and is not explicitly destroyed from the script will be automatically destroyed by the STAB system upon level exit.

There are several utility functions for manipulating STAB objects. STAB_GetSize returns the number of elements in a STAB object. To retrieve a specific string, STAB_GetElem returns a string at a specific index. To retrieve strings by matching the associated float value, call STAB_GetElemByFloat. If you worried about using exact float compares and want to match values by rounding to the nearest integer, call STAB_GetElemByInt.

To sort the elements of a STAB object in a case-sensitive manner, call STAB_SortByString. To perform a case-insensitive sort, call STAB_SortByStringI. To sort by associated float values, call STAB_SortByValue.

Docs courtesy of the creator of STAB, Joey.