Help: listappend()

Showing help on 'listappend()'

Syntax: listinsert (LIST <list>, <value> [, INT <index>]) => list
listappend (LIST <list>, <value> [, INT <index>]) => list

These functions return a copy of <list> with <value> added as a new element. `listinsert()' and `listappend()' add <value> before and after (respectively) the existing element with the given <index>, if provided.

The following three expressions always have the same value:

listinsert(<list>, <element>, <index>)
listappend(<list>, <element>, <index> - 1)
{@<list>[1..<index> - 1], <element>, @<list>[<index>..length(<list>)]}

If <index> is not provided, then `listappend()' adds the <value> at the end of the list and `listinsert()' adds it at the beginning; this usage is discouraged, however, since the same intent can be more clearly expressed using the list-construction expression, as shown in the examples below.

x = {1, 2, 3};
listappend(x, 4, 2) => {1, 2, 4, 3}
listinsert(x, 4, 2) => {1, 4, 2, 3}
listappend(x, 4) => {1, 2, 3, 4}
listinsert(x, 4) => {4, 1, 2, 3}
{@x, 4} => {1, 2, 3, 4}
{4, @x} => {4, 1, 2, 3}