Rewritten December 2023
FOREACH{'REVERSE} $$<itervar> in $<aryvay>({<startkey>{,<endkey>}})
<statements>
{IF <condition> REPEAT}
{IF <condition> EXIT}
{<statements>}
NEXT $$<itervar>
The FOREACH and FOREACH'REVERSE loops are used to iterate through Ordered Maps, which see for details.
As with other loops, the FOREACH loop body may contain nearly any legal statement, plus REPEAT and EXIT. In addition, the following only apply to FOREACH loops:
| • | $$<iterator> contains the value of the current key,value pair in the iteration |
| • | The .KEY() function may be used to extract the key from the current key,value pair. |
The FOREACH and FOREACH'REVERSE loops are used to iterate through Ordered Maps and Grid Maps, which see for details. Iteration proceeds in key order, starting with the first key (or the first key >= startkey if specified), and proceeding through the last key (or last key <= endkey if specified).
Examples
The loop below would list all of the state capitals, in alphabetical state order, until hitting the capital "Sacramento" after which it would exit.
dimx $state'capitals, ordmap(varstr;varstr) ! state -> capital
$state'capitals("Washington") = "Olympia"
...
foreach $$i in $state'capitals()
? "The capital of "; .key($$i); " state is "; $$i
if $$i = "Sacramento" exit
next $$i
The variation below would list the states in reverse alphabetical order, but only listing those that begin with "South"—i.e. starting with the first state <= "South!" and ending with the first state < "South". Note that FOREACH'REVERSE treats the startkey as relative to the reverse direction, i.e. the key >= the the first one to include in the iteration.
foreach'reverse $$i in $state'capitals("SouthZ","South")
? "The capital of "; .key($$i); " state is "; $$i
next $$i
The following shows three variations of iterating through a grid map.
dimx $gridi, gridmap(int;varstr;varstr)
...
foreach $$i in $gridi(3,3) ! iterate across row 3
...
foreach $$i in $gridi(srow,erow) ! iterate across row #'s srow to erow
...
foreach $$i in $gridi(srow) ! iterate from row # srow thru last row
...
See Also
History
2023 November, A-Shell 7.0.1752.0: endkey parameter extended to grid maps.
2023 October, A-Shell 7.0.1751.0: startkey support added to FOREACH'REVERSE; endkey added for ordered map iteration.
2023 August, A-Shell 6.5.1739: In FOREACH, if the specified starting key is not found, the iteration now starts with the next key. Previously, the result would have been an empty iteration. In FOREACH'REVERSE, the starting key is now recognized whereas previously it was ignored. As with FOREACH, if not found, the iteration starts with the next key—i.e. the next one lower in the collating sequence.
2018 May, A-Shell 6.5.1636, compiler edit 859: the starting key in a FOREACH statement may now be any kind of expression. Previously, it only allowed a simple variable or a literal string or numeric constant; numeric literals were allowed but weren't converted to string and thus typically failed to match any items in the map.
