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