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}
dst-list-src, src-list-ref
specify the destination and source lists, respectively, either as base arrays (e.g. $m() or as explicit iterator references (e.g. .REF($$i).
count
specifies the number of elements to move (defaulting to the entire src-list-ref)
dstpos
specifies the splice position within the destination list, according to the following:
Value |
Meaning |
|---|---|
-1 (default) |
end of the destination list |
0 |
the start of the destination list |
n (n > 0) |
after the nth item in the destination list |
Note that the dstpos parameter only applies when the destination list is expressed as a base array, e.g. $m(). Attempting to specify dstpos when the destination is expressed as an iterator or other individual element reference, e.g. .REF($$i), will result in a syntax error.
Example1
If $kids() contains the list: "john", "fred", "sally", "pilar", and $pets() contains the list "dog", "cat", "mouse", "lizard", then:
.SPLICE $kids(), $pets(), 1, 0
would splice "dog" to the start of the $kids() array.
.SPLICE $kids(), $pets(), 3, 2
would splice the first 3 pets ("dog", "cat", "mouse") after the 2nd kid, i.e. in between "fred" and "sally".
.SPLICE $kids(), $pets(), 0, -1
would be the same as
.SPLICE $kids(), $pets()
i.e. would splice all of the pets (count=0), to the end of the kids (-1).
.SPLICE $kids(), $pets(), 0, 0
would splice all of the pets to the start of the kids array.
Example2
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 that 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
