Syntax:
index$(element [,indexID]) = stringExpr$
Description:
This statement assigns the string specified by stringExpr$ to an element in one of the special index$ string arrays. The index$ string arrays have some features which are not available in a "normal" string array:
- Under the right circumstances, they can occupy less memory than a "normal" string array;
- There are certain useful operations that can only be performed on
index$ string arrays (see the index$ D, index$ I statements, and the indexf function).
The index$ string arrays are always global in scope. You can read the contents of an index$ array element by using the index$ function.
Your program can use up to ten index$ arrays, numbered 0 through 9. The indexID parameter specifies which index$ array to use; if you omit this parameter, index$ array 0 is used. The element parameter specifies which element to set within the selected index$ array.
Before you can assign values to an index$ array, your program must allocate space for the desired index$ array by executing one of the variants of the clear <index> statement (either "Syntax (1)" or "Syntax (2)"). You must execute a separate clear <index> statement for each of the index$ arrays (up to 10) that you wish to use. Depending on which variant of clear <index> you used to initialize the array, there may be additional restrictions on how you use the index$ statement:
- If you used the
clear numElements&,indexID,eltSize variant, then the element parameter you specify in the index$ statement should not exceed numElements& - 1, and the length of the string you assign should not exceed eltSize-1 characters.
- If you used the
clear bytes& [,indexID] variant, then the total memory occupied by all the strings you assign to that index$ array must not exceed bytes&.
You can use the mem function to determine whether you're approaching these limits, and you can use the clear <index> statement to increase an array's memory allocation if necessary.
Memory allocation
If the strings in your index$ array are to be of varying lengths, then you can save memory by specifying variable-length cells when you allocate memory for the array (use the clear bytes& [,indexID] syntax to do this). This is because of the two different storage schemes used by variable-length cells vs. fixed-length cells:
- Fixed-length cells (
clear numElements&,indexID,eltSize) always use eltSize bytes for every string in the array: this means there may be "unused" bytes following any giving string:
clear numElements&, indexID, 10
Actual memory needed for these 5 elements: 50 bytes
- Variable-length cells (
clear bytes& [,indexID]) are stored contiguously in memory: there are no "wasted" bytes between strings:
clear numBytes&, indexID
Actual memory needed for these 5 elements: 38 bytes
The tradeoff is this: although variable-length cells can save you memory, they also involve more complex internal memory management. Operations involving fixed-length cells generally execute somewhat faster.
Note:
You can use the mem function to retrieve various kinds of information about the status of an index$ array.
See Also:
index$ function; indexf; index$ I; index$ D; clear <index>
