A Guide to the S-Lang Language: Lists

Next Previous Contents

## 14. Lists

Sometimes it is desirable to utilize an object that has many of the properties of an array, but can also easily grow or shrink upon demand. The `List_Type` object has such properties.

An empty list may be created either by the `list_new` function or more simply using curly braces, e.g.,

> `

>         list = {};

> `

More generally a list of objects may be created by simply enclosing them in braces. For example,

> `

>        list = { "hello", 7, 3.14, {&sin, &cos}}

> `

specifies a list of 4 elements, where the last element is also a list. The number of items in a list may be obtained using the `length` function. For the above list, `length(list)` will return 4.

One may examine the contents of the list using an array index notation. For the above example, `list[0]` refers to the zeroth element of the list (`"hello"` in this case). Similarly,

> `

>         list[1] = [1,2,3];

> `

changes the first element of the list (7) to the array `[1,2,3]`. Also as the case for arrays one may index from the end of the list using negative indices, e.g., `list[-1]` refers to the last element of the list.

The functions `list_insert` and `list_append` may be used to add items to a list. In particular, `list_insert(list,obj,nth)` will insert the object `obj` into the list at the `nth` position. Similarly, `list_append(list,obj,nth)` will insert the object `obj` into the list right after `nth` position. If

> `

>        list = { "hello", 7, 3.14, {&sin, &cos}}

> `

then

> `

>        list_insert (list, 0, "hi");
>        list_append (list, 0, "there");
>        list_insert (list, -1, "before");
>        list_append (list, -1, "after");

> `

will result in the list

> `

>        {"hi", "there", "hello", 7, 3.14, "before", {&sin,&cos}, "after"}

> `

One might be tempted to use

> `

>        list = {"hi", list};

> `

to insert `"hi"` at the head of the list. However, this simply creates a new list of two items: `hi` and the original list.

Items may be removed from a list via the `list_delete` function, which deletes the item from the specified position and shrinks the list. In the context of the above example,

> `

>        list_delete (list, 2);

> `

will shrink the list to

> `

>        {"hi", "there", 7, 3.14, "before", {&sin,&cos}, "after"}

> `

Another way of removing items from the list is to use the `list_pop` function. The main difference between it and `list_delete` is that `list_pop` returns the deleted item. For example,

> `

>        item = list_pop (list, -2);

> `

would reduce the list to

> `

>        {"hi", "there", 7, 3.14, "before", "after"}

> `

and assign `{&sin,&cos}` to `item`. If the position parameter to `list_pop` is left unspecified, then the position will default to the zeroth, i.e., `list_pop(list)` is equaivalent to `list_pop(list,0)`.

To copy a list, use the dereference operator `@`:

> `

>        new_list = @list;

> `

Keep in mind that this does not perform a so-called deep copy. If any of the elements of the list are objects that are assigned by reference, only the references will be copied.

The `list_reverse` function may be used to reverse the elements of a list. Note that this does not create a new list. To create new list that is the reverse of another, copy the original using the dereference operator (@) and reverse that, i.e.,

> `

>         new_list = list_reverse (@list);

> `

Next Previous Contents