Read array

Purpose: Get data from an array.

 read-array <array> \
     key <key> \
     value <value> \
     [ delete [ <delete> ] ]
     [ status [ <status> ] ]

Copied!

read-array will obtain an element from <array> (that was created with new-array); an element obtained is <value> (in "value" clause) based on a number <key> (in "key" clause). <key> is a number from 0 up to (excluding) the currently allocated array size. The type of <value> is determined when <array> is created (see "type" clause), and can be either a string, number or a boolean.

You can also delete an element from the array by using "delete" clause - the <value> is still obtained though it is no longer in the array. The array element is deleted if "delete" clause is used without boolean variable <delete>, or if <delete> evaluates to true. "Deleting" means that an element will no longer hold a valid value; when such an element is read, for a string array it would be an empty string, for a number array it would be 0, and for a boolean array it would be false. The only way to distinguish those from existing array elements with the same values is to obtain <status> number variable (in "status" clause), which is GG_OKAY if an array element is set and not deleted, or GG_ERR_EXIST if an array element was never set or was deleted.

Note that array may be allocated beyond the highest index of an element written to it; reading from such elements that have never been written to will produce an empty string, a number 0 or a boolean false value (depending on the type of array).

Subscription shortcut

You can also get the value of an <array> element by using subscription operator ([]), for instance here you'd reference the 3rd element of array 'arr' in the comparison statement:

 new-array arr type number
 write-array arr key 3 value 20
 if-true arr[3] equal 20
     @Yes it's 20
 end-if

Copied!

This works for any array type, so you can use the subscriptive form of <array>[<index>] in any expression, where <index> is a number.

Examples

In this example, a new array is created, a value is written to it, and then the value is obtained and the element deleted:

 // Create new array
 new-array arr type string

 // Write to array
 write-array arr key 500 value "some data"

 // Read from array
 read-array arr key 500 value res delete
 @Deleted value is <<print-out res>>

Copied!