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.