Module list
Doubly-linked Lists.
A list is either a container (has pointer or integer values) stored inside
ListEntry nodes as the data field, or the objects themselves are nodes (declared with
LIST_HEADER up front in the struct).
The nodes of a container list are not ref-counted and are simply freed. The contained values may be ref-counted and will then be unref'd when the container is disposed.
Container lists are either pointer-like or string-like; if LIST_STRING flag bit
is set then we'll use strcmp for ordering and finding, otherwise simple ordering
is used, which is also fine for integer values (up to intptr_t or uintptr_t in
size)
See test-list.c
Functions
| list_new_ptr () | simple list containing pointers or integers. |
| list_new_str () | list containing refcounted strings. |
| list_new_ref () | list containing any other refcounted objects. |
| list_new_node (str) | list made of suitable structs with LIST_HEADER. |
| list_size (ls) | size of list. |
| list_item_data (ls, item) | data of list item. |
| list_start (ls) | first list item. |
| list_end (ls) | last list item. |
| list_iter_next (le) | advance to next item. |
| list_iter_prev (le) | move to previous item. |
| list_add (ls, data) | add data to the end of the list. |
| list_add_items (the, ...) | append a number of data items to a list. |
| list_insert (ls, before, data) | inserts data before before |
| list_insert_front (ls, data) | insert data at the start of the list. |
| list_add_sorted (ls, data) | add data in sorted order. |
| list_add_unique (ls, data) | only add data if not already present in list. |
| list_remove (ls, item) | removes item from list. |
| list_delete (ls, item) | remove item from list, deleting node data if needed. |
| list_pop (ls) | remove the last item and return its value. |
| list_find (ls, data) | return an iterator to a given data value. |
| list_iter (ls, idx) | get iter at index. |
| list_get (ls, idx) | get data at index. |
| list_filter (other, fun) | make a new list containing list data that match a predicate. |
| list_filter_if (other, fun, data) | make a new list of the list items that match a predicate. |
| list_copy (other) | make a copy of another list. |
| list_extend_move (ls, other) | extend a list by appending another list’s contents, emptying it. |
| list_extend_copy (ls, other) | extend a list by appending another list’s contents, copying it. |
| list_advance (ls, iter, len) | move a list iterator along a given number of times. |
| list_slice (other, begin, end) | create a new list from another between two iterators. |
| list_slice_n (other, begin, len) | extract a new list from a start iterator for a given number of items. |
| list_erase (ls, begin, end) | erase items between two iterators. |
| list_erase_n (ls, begin, n) | erase n items from an iterator. |
| list_item_compare (ls, cmp) | set the comparison operation for the objects in this list. |
| list_item_equals (ls, cmp) | set the equality operation for the objects in this list. |
| list_remove_value (ls, data) | remove an item by data value, dispoing it. |
| list_to_array (ls) | make an array out of a list. |
| list_new_from_array (type, arr, sz) | make a list out of an array of pointers or strings. |
Structs
| List | List type |
Types
| ListIter | List iterator type |
Statement Macros
| FOR_LIST_ITEM | iterate over list items. |
| FOR_LIST | iterate over default list items. |
Functions
- list_new_ptr ()
- simple list containing pointers or integers.
- list_new_str ()
- list containing refcounted strings.
- list_new_ref ()
- list containing any other refcounted objects.
- list_new_node (str)
-
list made of suitable structs with
LIST_HEADER.Parameters:
- str bool
Returns:
- list_size (ls)
-
size of list.
Parameters:
- ls List *
Returns:
-
int
- list_item_data (ls, item)
-
data of list item.
Parameters:
- ls List *
- item void *
Returns:
-
void *
- list_start (ls)
-
first list item.
Parameters:
- ls List *
Returns:
- list_end (ls)
-
last list item.
Parameters:
- ls List *
Returns:
- list_iter_next (le)
-
advance to next item.
Parameters:
- le ListIter
Returns:
- list_iter_prev (le)
-
move to previous item.
Parameters:
- le ListIter
Returns:
- list_add (ls, data)
-
add data to the end of the list.
Parameters:
- ls List *
- data void *
Returns:
- list_add_items (the, ...)
-
append a number of data items to a list.
Assumes that the last argument is NULL, so not so
useful for lists of arbitrary integers.
Parameters:
- the List* list
- ... values (must be pointer sized!)
- list_insert (ls, before, data)
-
inserts data before
beforeParameters:
Returns:
- list_insert_front (ls, data)
-
insert data at the start of the list.
Parameters:
- ls List *
- data void *
Returns:
- list_add_sorted (ls, data)
-
add data in sorted order.
Parameters:
- ls List *
- data void *
Returns:
- list_add_unique (ls, data)
-
only add data if not already present in list.
Parameters:
- ls List *
- data void *
- list_remove (ls, item)
-
removes item from list.
Parameters:
Returns:
- list_delete (ls, item)
-
remove item from list, deleting node data if needed.
Parameters:
Returns:
-
void *
- list_pop (ls)
-
remove the last item and return its value.
For container lists, this frees the item.
Parameters:
- ls List *
Returns:
-
void *
- list_find (ls, data)
-
return an iterator to a given data value.
Parameters:
- ls List *
- data void *
Returns:
- list_iter (ls, idx)
-
get iter at index.
Negative indices count from the back, so -1 is the last entry, etc.
Not particularly efficient for arbitrary indexing since this is O(N).
Parameters:
- ls List *
- idx int
Returns:
- list_get (ls, idx)
-
get data at index.
This is only different from list_iter when it’s a container list.
Parameters:
- ls List *
- idx int
Returns:
-
void *
- list_filter (other, fun)
-
make a new list containing list data that match a predicate.
Parameters:
- other List *
- fun ListPred
Returns:
- list_filter_if (other, fun, data)
-
make a new list of the list items that match a predicate.
Parameters:
- other List *
- fun ListSearchFn
- data void *
Returns:
- list_copy (other)
-
make a copy of another list.
Parameters:
- other List *
Returns:
- list_extend_move (ls, other)
-
extend a list by appending another list’s contents, emptying it.
Parameters:
Returns:
- list_extend_copy (ls, other)
-
extend a list by appending another list’s contents, copying it.
Parameters:
Returns:
- list_advance (ls, iter, len)
-
move a list iterator along a given number of times.
Parameters:
- ls List *
- iter ListIter *
- len int
Returns:
-
bool
- list_slice (other, begin, end)
-
create a new list from another between two iterators.
Parameters:
Returns:
- list_slice_n (other, begin, len)
-
extract a new list from a start iterator for a given number of items.
Parameters:
Returns:
- list_erase (ls, begin, end)
-
erase items between two iterators.
Opposite operation to list_slice
Parameters:
- list_erase_n (ls, begin, n)
-
erase n items from an iterator.
Parameters:
- list_item_compare (ls, cmp)
-
set the comparison operation for the objects in this list.
Parameters:
- ls List *
- cmp ListCmpFun
- list_item_equals (ls, cmp)
-
set the equality operation for the objects in this list.
Parameters:
- ls List *
- cmp ListEqualsFun
- list_remove_value (ls, data)
-
remove an item by data value, dispoing it.
Parameters:
- ls List *
- data void *
Returns:
-
bool
- list_to_array (ls)
-
make an array out of a list.
Parameters:
- ls List *
Returns:
-
void * *
an array of data objects
- list_new_from_array (type, arr, sz)
-
make a list out of an array of pointers or strings.
Parameters:
- type int either LIST_POINTER or LIST_STRING
- arr void * * the array
- sz int size of array; if -1 then assume this is a NULL-terminated array
Returns: