# Splicing Lists

> [HTML Version](splicinglists.htm)

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](foreach.md) 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](foreach.md) 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**

- [SPLICE Parameter DSTPOS](spliceparameterdstpos.md)