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