1\function{list_append}
2\synopsis{Append an object to a list}
3\usage{list_append (List_Type list, object [,Int_Type nth])}
4\description
5  The \ifun{list_append} function is like \ifun{list_insert} except
6  this function appends the object to the list.  The optional
7  argument \exmp{nth} may be used to specify where the object is to be
8  appended.  See the documentation on \ifun{list_insert} for more details.
9\seealso{list_concat, list_insert, list_join, list_delete, list_pop, list_new, list_reverse}
10\done
11
12\function{list_concat}
13\synopsis{Concatenate two lists to form a third}
14\usage{List_Type = list_concat (List_Type a, List_Type b)}
15\description
16  This function creates a new list that is formed by concatenating the
17  two lists \exmp{a} and \exmp{b} together.  Neither of the input
18  lists are modified by this operation.
19\seealso{list_join, list_append, list_insert}
20\done
21
22\function{list_delete}
23\synopsis{Remove an item from a list}
24\usage{list_delete (List_Type list, Int_Type nth)}
25\description
26  This function removes the \exmp{nth} item in the specified list.
27  The first item in the list corresponds to a value of \exmp{nth}
28  equal to zero.  If \exmp{nth} is negative, then the indexing is with
29  respect to the end of the list with the last item corresponding to
30  \exmp{nth} equal to -1.
31\seealso{list_insert, list_append, list_pop, list_new, list_reverse}
32\done
33
34\function{list_insert}
35\synopsis{Insert an item into a list}
36\usage{list_insert (List_Type list, object [,Int_Type nth])}
37\description
38  This function may be used to insert an object into the specified
39  list.  With just two arguments, the object will be inserted at the
40  beginning of the list.  The optional third argument, \exmp{nth}, may
41  be used to specify the insertion point.  The first item in the list
42  corresponds to a value of \exmp{nth} equal to zero.  If \exmp{nth}
43  is negative, then the indexing is with respect to the end of the
44  list with the last item given by a value of \exmp{nth} equal to -1.
45\notes
46  It is important to note that
47#v+
48    list_insert (list, object, 0);
49#v-
50  is not the same as
51#v+
52    list = {object, list}
53#v-
54  since the latter creates a new list with two items, \exmp{object}
55  and the old list.
56\seealso{list_append, list_pop, list_delete, list_new, list_reverse}
57\done
58
59\function{list_join}
60\synopsis{Join the elements of a second list onto the end of the first}
61\usage{list_join (List_Type a, List_Type b)}
62\description
63  This function modifies the list \exmp{a} by appending the elements
64  of \exmp{b} to it.
65\seealso{list_concat, list_append, list_insert}
66\done
67
68\function{list_new}
69\synopsis{Create a new list}
70\usage{List_Type list_new ()}
71\description
72  This function creates a new empty \dtype{List_Type} object.  Such a
73  list may also be created using the syntax
74#v+
75     list = {};
76#v-
77\seealso{list_delete, list_insert, list_append, list_reverse, list_pop}
78\done
79
80\function{list_pop}
81\synopsis{Extract an item from a list}
82\usage{object = list_pop (List_Type list [, Int_Type nth])}
83\description
84  The \ifun{list_pop} function returns a object from a list deleting
85  the item from the list in the process.  If the second argument is
86  present, then it may be used to specify the position in the list
87  where the item is to be obtained.  If called with a single argument,
88  the first item in the list will be used.
89\seealso{list_delete, list_insert, list_append, list_reverse, list_new}
90\done
91
92\function{list_reverse}
93\synopsis{Reverse a list}
94\usage{list_reverse (List_Type list)}
95\description
96  This function may be used to reverse the items in list.
97\notes
98  This function does not create a new list.  The list passed to the
99  function will be reversed upon return from the function.  If it is
100  desired to create a separate reversed list, then a separate copy
101  should be made, e.g.,
102#v+
103     rev_list = @list;
104     list_reverse (rev_list);
105#v-
106\seealso{list_new, list_insert, list_append, list_delete, list_pop}
107\done
108
109\function{list_to_array}
110\synopsis{Convert a list into an array}
111\usage{Array_Type list_to_array (List_Type list [,DataType_Type type])}
112\description
113 The \ifun{list_to_array} function converts a list of objects into an
114 array of the same length and returns the result.  The optional
115 argument may be used to specify the array's data type.  If no
116 \exmp{type} is given, \ifun{list_to_array} tries to find the common
117 data type of all list elements. This function will generate an
118 exception if the list is empty and no type has been specified, or the
119 objects in the list cannot be converted to a common type.
120\notes
121 A future version of this function may produce an \dtype{Any_Type}
122 array for an empty or heterogeneous list.
123\seealso{length, typecast, __pop_list, typeof, array_sort}
124\done
125
126