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
See Also
| • | .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. |
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.
