Go to the first, previous, next, last section, table of contents.

#### 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}
```

Go to the first, previous, next, last section, table of contents.