One or more elements from one list can be spliced on to another using the dot-statement .SPLICE. Note no elements are actually allocated or deleted in this operation; they are just moved from the source list to the destination list. The general syntax for the .SPLICE statement is:
.SPLICE dst-list-ref, src-list-ref {, count} {, dstpos}
See the next topic for information on dstpos.
If count (number of elements to move) is not specified, the operation moves all of the elements starting from the src-list-ref position. The list-ref parameters may be list base references, e.g. $m(), or they may be references to a particular element by iterator reference, e.g. .REF($$i). For example:
.SPLICE $m(), $m2()
The above case splices the entire $m2() list to the end of the $m() list. Afterward, the $m2() list will be empty (but still valid).
.SPLICE $m(), $m2(), 1
Same as the previous case except only the first element of $m2() is spliced to the end of $m().
To splice from the middle of the source list, specify a position via an iterator reference. For example, to move the 3rd and 4th items from $m2() to the end of $m1() ...
count = 0
foreach $$i in $m2()
count += 1
if count = 3 then ! 3rd iterated item
.SPLICE $m(), .REF($$i), 2 ! splice 3rd & 4th items
exit ! iterator corrupted after splice! must exit!
endif
next $$i
The .REF($$i) iterator technique also works for the destination, i.e. to insert at a destination other than the end of the target list. To splice from an arbitrary Xth position in the source to the Yth position in the destination, use a double-nested FOREACH loop:
! splice count elements from position srcpos in m1$() to dstpos in m2$
idst = 0 ! counter for dest position
foreach $$i in $m2()
idst += 1
if idst >= dstpos then ! $$i is the dst splice-to position
isrc = 0
foreach $$j in $m1()
isrc += 1
if isrc >= srcpos ! $$j is the src splice-from position
.splice .ref($$i), .ref($$j), count
exit ! must exit after splice!
endif
next $$j
exit ! must exit after splice!
endif
next $$i
Note: as with other modifications to a collection, the use of .SPLICE corrupts the iterator; thus you must exit from the FOREACH loop after the .SPLICE operation. (In the above example, we have to exit from both loops.)
History
2016 October, A-Shell 1532: .SPLICE now accepts limited use of a reverse iterator, but only when the count is 1. Also, the third argument, count, can be any numeric expression.
Subtopics
