Reviewed and updated December 2025
Function |
Description |
|---|---|
.EXTENT($a()) |
Returns the number of elements (key-value pairs) in the ordered map $a. See .EXTENT() for more details. |
.ISNULL($a(key$)), .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 ... ! requires A$ >= 6 bytes
if .ISNULL(A$) then ... ! requires A$ >= 6 bytes
if .ISNULL($MYMAP(KEY$)) then ... ! works in all cases
IF NOT .ISNULL(A$) THEN ? "$MYMAP(KEY$) = ";A$
The first two tests in the example above only work if the variable (A$) is a string of at least 6 bytes in length because the internal representation of .NULL is the 6 byte string "<null>". So the third method is the most universal since $MYMAP(KEY$) will always return .NULL if the element doesn't exist, regardless of the ordered map type. However, the first two methods have the advantage of avoiding the need to retrieve the element from the ordered map a second time in order to use it (if not null). 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
See Also
History
2020 June, A-Shell 6.5.1683: Use of the .ISNULL() function now sets the minimum runtime version to 1414.
2019 November, A-Shell 6.5.1671: Add error on non-string argument.
2015 July, A-Shell 6.1.1413: Add .ISNULL().
