Next Previous Contents

8. Functions that Create and Manipulate Lists

8.1 list_append

Synopsis

Append an object to a list

Usage

list_append (List_Type list, object [,Int_Type nth])

Description

The list_append function is like list_insert except this function appends the object to the list. The optional argument nth may be used to specify where the object is to be appended. See the documentation on list_insert for more details.

See Also

list_concat, list_insert, list_join, list_delete, list_pop, list_new, list_reverse

8.2 list_concat

Synopsis

Concatenate two lists to form a third

Usage

List_Type = list_concat (List_Type a, List_Type b)

Description

This function creates a new list that is formed by concatenating the two lists a and b together. Neither of the input lists are modified by this operation.

See Also

list_join, list_append, list_insert

8.3 list_delete

Synopsis

Remove an item from a list

Usage

list_delete (List_Type list, Int_Type nth)

Description

This function removes the nth item in the specified list. The first item in the list corresponds to a value of nth equal to zero. If nth is negative, then the indexing is with respect to the end of the list with the last item corresponding to nth equal to -1.

See Also

list_insert, list_append, list_pop, list_new, list_reverse

8.4 list_insert

Synopsis

Insert an item into a list

Usage

list_insert (List_Type list, object [,Int_Type nth])

Description

This function may be used to insert an object into the specified list. With just two arguments, the object will be inserted at the beginning of the list. The optional third argument, nth, may be used to specify the insertion point. The first item in the list corresponds to a value of nth equal to zero. If nth is negative, then the indexing is with respect to the end of the list with the last item given by a value of nth equal to -1.

Notes

It is important to note that

    list_insert (list, object, 0);
is not the same as
    list = {object, list}
since the latter creates a new list with two items, object and the old list.

See Also

list_append, list_pop, list_delete, list_new, list_reverse

8.5 list_join

Synopsis

Join the elements of a second list onto the end of the first

Usage

list_join (List_Type a, List_Type b)

Description

This function modifies the list a by appending the elements of b to it.

See Also

list_concat, list_append, list_insert

8.6 list_new

Synopsis

Create a new list

Usage

List_Type list_new ()

Description

This function creates a new empty List_Type object. Such a list may also be created using the syntax

     list = {};

See Also

list_delete, list_insert, list_append, list_reverse, list_pop

8.7 list_pop

Synopsis

Extract an item from a list

Usage

object = list_pop (List_Type list [, Int_Type nth])

Description

The list_pop function returns a object from a list deleting the item from the list in the process. If the second argument is present, then it may be used to specify the position in the list where the item is to be obtained. If called with a single argument, the first item in the list will be used.

See Also

list_delete, list_insert, list_append, list_reverse, list_new

8.8 list_reverse

Synopsis

Reverse a list

Usage

list_reverse (List_Type list)

Description

This function may be used to reverse the items in list.

Notes

This function does not create a new list. The list passed to the function will be reversed upon return from the function. If it is desired to create a separate reversed list, then a separate copy should be made, e.g.,

     rev_list = @list;
     list_reverse (rev_list);

See Also

list_new, list_insert, list_append, list_delete, list_pop

8.9 list_to_array

Synopsis

Convert a list into an array

Usage

Array_Type list_to_array (List_Type list [,DataType_Type type])

Description

The list_to_array function converts a list of objects into an array of the same length and returns the result. The optional argument may be used to specify the array's data type. If no type is given, list_to_array tries to find the common data type of all list elements. This function will generate an exception if the list is empty and no type has been specified, or the objects in the list cannot be converted to a common type.

Notes

A future version of this function may produce an Any_Type array for an empty or heterogeneous list.

See Also

length, typecast, __pop_list, typeof, array_sort


Next Previous Contents