Special ORDMAP Functions

Modified July 2015; see history

Function

Description

.EXTENT($a())

Returns the extent of the ordered map $a, which is equivalent to the overall number of elements in the map. If the map has not yet been initialized (i.e. the compiler has seen the dimx statement but it was not yet executed at runtime, or it was executed and then freed with redimx), .EXTENT will return -1. Note that .extent functions effectively the same way on other array types.

.ISNULL(var)

Tests for the .NULL condition. See example below.

.KEY($$i)

Returns the key associated with the element currently indexed by the iterator.

.NEXT($$i)

Advances the iterator, returning the associated key or .null if no more. This is mainly used internally by the next $$i statement, which is translated to something like:

    if .next($$i) # .null <repeat loop>

.NULL

Does not operate on anything but may be used to test for a null element as opposed to one whose value is "". It may also be used in an assignment to delete an element, i.e. assigning an element the value .null deletes that element.

 

.ISNULL() Example

A$ = $MYMAP(KEY$)

IF A$ = .NULL THEN ? "No such key in map"   ! old method (now deprecated)

IF .ISNULL(A$) THEN ? "No such key in map"  ! new method

 

Both methods of checking for .NULL are equivalent, provided that the map contains only string elements and A$ is a string. The .ISNULL(var) method is preferred, as it works for non-string elements also. See examples notes under Accessing elements for more details.    

 

History

2015 July, A-Shell 6.1.1413:  Add ISNULL.