Added April 2018
Adding, deleting or modifying keys while iterating will render the iterator unpredictable, and thus should be strictly avoided. You may, however, modify the values of the key-value pairs as you iterate through them, either by using the .key() function or by assigning a new value to the iterator directly; see History below. For example, the loop below shows both methods of modifying the value of each element by prefixing it with “Beautiful” and folding the preexisting part to upper case, assuming varstr elements:
foreach $$i in $capitals() ! fwd iterator
$capitals(.key($$i)) = "Beautiful " + ucs($$i) ! method 1
! or...
$$i = "Beautiful " + ucs($$i) ! method 2
next $$i
Note that while setting an iterator to .NULL (to delete the key-value pair) is considered an error, a possible alternative would be to set the value to "" thereby preserving the key-value position in the ordmap but perhaps indicating to your own application to ignore the item. Another approach would be to copy the items you want to keep during the iteration to another ordmap. The following example illustrates both techniques, selectively copying a portion of the ordered map $state1 (i.e. capital cities and their states) to a new ordered map $state2, which will contain just the capitals starting with "C". We also clear the value associated with the capital "Cococabana" in the source ordmap before copying it.
dimx $state1, ordmap(varstr;varstr) ! capital -> state
dimx $state2, ordmap(varstr;varstr) ! capital (starting with C) -> state
map1 cap$,s,40
...
foreach $$i in $state1("C","Czz") ! >= "C", <= "Czz"
cap$ = .key($$i)
if cap$ = "cococabana" then
$$i = "" ! $state1("cococabana") -> ""
endif
$state2(cap$) = $$i
next $$j
Note that in the above example, we didn't have to introduce the temporary variable caps$, but doing so probably increases efficiency by eliminating redundant use of the .key($$i) operation. Ordered map operations are extremely efficient given what they involve, but they are still considerably more costly than ordinary variable or array references, particularly as the map gets large. Also note that as with other control loops, the control statements EXIT and REPEAT are available.
Notes:
| • | This technique works with all collection types: ORDMAP, ORDMAPM, GRIDMAPS, GRIDMAPI, MLIST. |
| • | In the case of ORDMAPM, it is the only way to change the value of an existing element for which there are duplicate keys. |
| • | In the case of ORDMAP, the direct assignment to the iterator in the above example would be equivalent to ... |
$state1(.key($$i)) = ""
| ... except much faster, since the key lookup, deletion, and re-addition steps are all eliminated. |
| • | In the case of MLIST, it eliminates the need for the .ref($$i) function, (which is now effectively deprecated). |
| • | The iterator is only writeable when it appears on the left side of the equals sign in an assignment statement. In all other cases, particularly when passing an iterator as an argument to a function, it remains read-only. |
History
2025 February, A-Shell 7.0.1770, compiler edit 1063: Compiler now treats explicit deletions to ordered maps during iteration as errors—i.e., invalid collection operation or reference.
2023 November, A-Shell 7.0.1752: Extend foreach statement to gridmaps for iterating across a row.
2023 October, A-Shell 7.0.1751: Support for endkey parameter added.
2023 August, A-Shell 6.5.1739: If startkey not found, iteration now starts with the next key. Previously the result would have been an empty iteration. Add support for startkey to foreach'reverse, which previously would have been ignored.
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.
2018 April, A-Shell 6.5.1633: Writeable Interators added to A-Shell.
