The List Library
0.2.1
|
Source for List Library (CDSL) More...
#include <stdarg.h>
#include <stddef.h>
#include "cbl/assert.h"
#include "cbl/memory.h"
#include "list.h"
Functions | |
list_t *() | list_push (list_t *list, void *data) |
pushes a new node to a list. | |
list_t *() | list_list (void *data,...) |
constructs a new list using a sequence of data. | |
list_t *() | list_append (list_t *list, list_t *tail) |
appends a list to another. | |
list_t *() | list_copy (const list_t *list) |
duplicates a list. | |
list_t *() | list_pop (list_t *list, void **pdata) |
pops a node from a list and save its data (pointer) into a pointer object. | |
list_t *() | list_reverse (list_t *list) |
reverses a list. | |
size_t() | list_length (const list_t *list) |
counts the length of a list. | |
void() | list_free (list_t **plist) |
destroys a list. | |
void() | list_map (list_t *list, void apply(void **, void *), void *cl) |
calls a user-provided function for each node in a list. | |
void **() | list_toarray (const list_t *list, void *end) |
converts a list to an array. |
Source for List Library (CDSL)
list_t*() list_append | ( | list_t * | list, |
list_t * | tail | ||
) |
appends a list to another.
list_append() combines two lists by appending tail
to list
, which makes the next pointer of the last node in list
point to the first node of tail
.
Possible exceptions: mem_exceptfail
Unchecked errors: foreign data structure given for list
and tail
[in,out] | list | list to which tail appended |
[in] | tail | list to append to list |
list
duplicates a list.
list_copy() creates a new list by copying nodes of list
.
Possible exceptions: mem_exceptfail
Unchecked errors: foreign data structure given for list
list
are not duplicated. An empty list results in returning a null pointer, which means an empty list.[in] | list | list to duplicate |
destroys a list.
list_free() destroys a list by deallocating storages for each node. After the call, the list is empty, which means that it makes a null pointer. If plist
points to a null pointer, list_free() does nothing since it is already empty.
Possible exceptions: none
Unchecked errors: pointer to foreign data structure given for plist
plist
is a double pointer to list_t
.[in,out] | plist | pointer to list to destroy |
size_t() list_length | ( | const list_t * | list | ) |
counts the length of a list.
list_length() counts the number of nodes in list
.
Possible exceptions: none
Unchecked errors: foreign data structure given for list
[in] | list | list whose nodes counted |
constructs a new list using a sequence of data.
list_list() constructs a list whose nodes contain a sequence of data given as arguments; the first argument is stored in the head (first) node, the second argument in the second node and so on. There should be a way to mark the end of the argument list, which a null pointer is for. Any argument following a null pointer argument is not invalid, but ignored.
Possible exceptions: mem_exceptfail
Unchecked errors: none
[in] | data | data to store in head node of new list |
[in] | ... | other data to store in new list |
calls a user-provided function for each node in a list.
For each node in a list, list_map() calls a user-provided callback function; it is useful when doing some common task for each node. The pointer given in cl
is passed to the second parameter of a user callback function, so can be used as a communication channel between the caller of list_map() and the callback. Since the callback has the address of data
(as opposed to the value of data
) through the first parameter, it is free to change its content. One of cases where list_map() is useful is to deallocate storages given for data
of each node. Differently from the original implementation, this library also provides a marco named LIST_FOREACH() that can be used in the similar situation.
Possible exceptions: none (user-provided function may raise some)
Unchecked errors: foreign data structure given for list
, user callback function doing something wrong (see the warning below)
[in,out] | list | list with which apply called |
[in] | apply | user-provided function (callback) |
[in] | cl | passing-by argument to apply |
pops a node from a list and save its data (pointer) into a pointer object.
list_pop() copies a pointer value stored in the head node of list
to a pointer object pointed to by pdata
and pops the node. If the list is empty, list_pop() does nothing and just returns list
. If pdata
is a null pointer list_pop() just pops without saving any data.
Possible exceptions: none
Unchecked errors: foreign data structure given for list
[in] | list | list from which head node popped |
[out] | pdata | points to pointer into which data (pointer value) stored |
pushes a new node to a list.
list_push() pushes a pointer value data
to a list list
with creating a new node. A null pointer given for list
is considered to indicate an empty list, thus not treated as an error.
Possible exceptions: mem_exceptfail
Unchecked errors: foreign data structure given for list
[in] | list | list to which data pushed |
[in] | data | data to push into list |
list_t*() list_reverse | ( | list_t * | list | ) |
reverses a list.
list_reverse() reverses a list, which eventually makes its first node the last and vice versa.
Possible exceptions: none
Unchecked errors: foreign data structure given for list
[in] | list | list to reverse |
void**() list_toarray | ( | const list_t * | list, |
void * | end | ||
) |
converts a list to an array.
list_toarray() converts a list to an array whose elements correspond to the data stored in nodes of the list. This is useful when, say, sorting a list. A function like array_tolist() is not necessary because it is easy to construct a list scanning elements of an array, for example:
for (i = 0; i < ARRAY_SIZE; i++) list = list_push(list, array[i]);
The last element of the constructed array is assigned by end
, which is a null pointer in most cases. Do not forget to deallocate the array when it is unnecessary.
Possible exceptions: mem_exceptfail
Unchecked errors: foreign data structure given for list
[in] | list | list to convert to array |
[in] | end | end-mark to save in last element of array |