Special ORDMAP Functions

Updated December 2019; 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. See example under Iterators.
.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>

.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

IF NOT .ISNULL(A$) THEN ? "$MYMAP(KEY$) = ";A$

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. Note that since .ISNULL() returns a proper boolean value, you can negate it with the unary NOT operator to test if the item exists.

Comments

Use of the .ISNULL() function sets the minimum runtime version to 1414. See History.

Attempting to use the .ISNULL() function with a non-string argument generates an illegal expression error. See History.

Side note: although this addresses one mistaken use of .ISNULL(), it doesn't address the case where the argument is a string or structure variable but is less than 6 characters long. For example, this works:

IF .ISNULL($MAP(A$)) THEN ... ! good

but this only works if VAR is an S or X type (or structure) at least 6 bytes long:

VAR = $MAP(A$)

IF .ISNULL(VAR) THEN ... ! only good if sizeof(VAR)>=6