Operations on Lists

Function: int length (list list)

Returns the number of elements in list. It is also permissible to pass a string to length(); see the description in the previous section.

length({1, 2, 3})   =>   3
length({})          =>   0

Function: int is_member (value, list list)

Returns true if there is an element of list that is completely indistinguishable from value. This is much the same operation as "value in list" except that, unlike in, the is_member() function does not treat upper- and lower-case characters in strings as equal.

"Foo" in {1, "foo", #24}            =>   2
is_member("Foo", {1, "foo", #24})   =>   0
is_member("Foo", {1, "Foo", #24})   =>   2

Function: list listinsert (list list, value [, int index])

Function: list listappend (list list, value [, int index])

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}

Function: list listdelete (list list, int index)

Returns a copy of list with the indexth element removed. If index is not in the range [1..length(list)], then E_RANGE is raised.

x = {"foo", "bar", "baz"};
listdelete(x, 2)   =>   {"foo", "baz"}

Function: list listset (list list, value, int index)

Returns a copy of list with the indexth element replaced by value. If index is not in the range [1..length(list)], then E_RANGE is raised.

x = {"foo", "bar", "baz"};
listset(x, "mumble", 2)   =>   {"foo", "mumble", "baz"}

This function exists primarily for historical reasons; it was used heavily before the server supported indexed assignments like x[i] = v. New code should always use indexed assignment instead of `listset()' wherever possible.

Function: list setadd (list list, value)

Function: list setremove (list list, value)

Returns a copy of list with the given value added or removed, as appropriate. setadd() only adds value if it is not already an element of list; list is thus treated as a mathematical set. value is added at the end of the resulting list, if at all. Similarly, setremove() returns a list identical to list if value is not an element. If value appears more than once in list, only the first occurrence is removed in the returned copy.

setadd({1, 2, 3}, 3)         =>   {1, 2, 3}
setadd({1, 2, 3}, 4)         =>   {1, 2, 3, 4}
setremove({1, 2, 3}, 3)      =>   {1, 2}
setremove({1, 2, 3}, 4)      =>   {1, 2, 3}
setremove({1, 2, 3, 2}, 2)   =>   {1, 3, 2}