Modified September 2019; see History
Beginning with A-Shell 6.5.1650, a language extension provides high level operations to copy, add, or subtract collections—i.e. ORDMAP, ORDMAPM and MLIST structures—to/from each other. Syntax:
$map1() = $map2() ! copy $map2() to $map1()
$map1() += $map2() ! add $map2() to $map1()
$map1() -= $map2() ! subtract elements matching $map2() from $map1()
Notes:
| • | The copy operation destroys any prior contents of the destination before copying the source to it. |
| • | The append operation adds elements from the source collection to the destination collection. If the destination is an ORDMAP, any key-value pairs with keys matching destination elements will be updated with the source value. If the source and destination are MLISTs, the append operation is equivalent to concatenating the source list to the end of the destination list. |
| • | The subtraction operation iterates through the source map and for each element, if the key exists in the destination map, that element is removed from the destination. If the destination is an ORDMAPM and there are multiple matching keys, only one is removed per source element (and you have no way of knowing which). Subtraction does not apply to MLIST. |
| • | These operations primarily make sense only for collections of the same type, i.e. ORDMAP to ORDMAP, or MLIST to MLIST. You may mix ORDMAP and and ORDMAPM, but note that the destination retains its original attributes. In other words, copying or appending an ORDMAPM to an ORDMAP does not change the fact that the destination is still an ORDMAP and thus cannot contain duplicate keys. (In this case, each source pair with a key matching an existing destination pair will result in that destination element being replaced with the new value.) Copying or appending ORDMAP collections to ORDMAPM collections makes perfect sense. The reverse is of dubious value due to the potential loss of elements with the same key. |
| • | Copying/appending between ordmap(varstr;varx) and ordmap(varstr;varstr) is legal, but only makes unambiguous sense when copying from (varstr;varstr) to (varstr;varx). That is, the varx format can store any data, but the varstr format cannot handle embedded nulls. However, no data is actually lost in either conversion; copying from varx to varstr and back to varx should be ok. |
History
2019 September, A-Shell 6.5.1668, compilter edit 918: The Shortcut Operators (+= and -=) are now accepted, along with the above longer forms.
2018 November, A-Shell 6.5.1650, compiler edit 888: Add function to A-Shell
