Lists

A list stores a collection of values in a particular order. You can add values at the end or insert them somewhere in the middle of the list. You can address the values using an index. Also you can sort the elements, either in ascending or descending order. Lists can be used in many ways, for example to store changing collections of values. They are implemented using simple arrays but, as this is done in compiled code it is a lot faster than using an array yourself. The following functions are available:

ds_list_create() Creates a new list. The function returns an integer as an id that must be used in all other functions to access the particular list.
ds_list_destroy(id) Destroys the list with the given id, freeing the memory used. Don't forget to call this function when you are ready with the structure.
ds_list_clear(id) Clears the list with the given id, removing all data from it but not destroying it.
ds_list_copy(id, source) Copies the list source into the list with the given id.
ds_list_size(id) Returns the number of values stored in the list.
ds_list_empty(id) Returns whether the list is empty. This is the same as testing whether the size is 0.
ds_list_add(id, val) Adds the value at the end of the list.
ds_list_insert(id, pos, val) Inserts the value at position pos in the list. The first position is 0, the last position is the size of the list minus 1.
ds_list_replace(id, pos, val) Replaces the value at position pos in the list with the new value.
ds_list_delete(id, pos) Deletes the value at position pos in the list. (Position 0 is the first element.)
ds_list_find_index(id, val) Find the position storing the indicated value. If the value is not in the list -1 is returned.
ds_list_find_value(id, pos) Returns the value stored at the indicated position in the list.
ds_list_sort(id, ascend) Sorts the values in the list. When ascend is true the values are sorted in ascending order, otherwise in descending order.
ds_list_shuffle(id) Shuffles the values in the list such that they end up in a random order.
ds_list_write(id) Turns the data structure into a string and returns this string. The string can then be used to e.g. save it to a file. This provides an easy mechanism for saving data structures.
ds_list_read(id, str) Reads the data structure from the given string (as created by the previous call).