List and Ddlist functions

This section provides prototypes and short descriptions of the useful functions available for List and Ddlist manipulation.

List   *link_alloc(void *ptr, int type)

Ddlist *dd_link_alloc(void *ptr, int type)

Allocate link of given type and set to point at ptr.

void    ref_set(List * el, void *ptr, int type)

void    dd_ref_set(Ddlist * el, void *ptr, int type)

Set list element el to reference ptr of given type.

List   *list_make(int n, int type)

Ddlist *dd_list_make(int n, int type)

Make and a list of length n of given type with NULL references.

List   *list_append(List * l1, List * l2)

Ddlist *dd_append(Ddlist * l1, Ddlist * l2)

Append list l2 on to end of l1 and return combined list.

List   *link_addtostart(List * list, List * el)
 
Ddlist *dd_link_addtostart(Ddlist * list, Ddlist * el)

Add new element to the start of the list returning new start of the list. If the element is NULL the old start of list will be returned.

List   *ref_addtostart(List * list, void *ptr, int type)

Ddlist *dd_ref_addtostart(Ddlist * list, void *ptr, int type)

Create a new element of given type referencing ptr and add it to the start of the list returning the new start of the list.

List   *link_addtoend(List * end, List * el)

Ddlist *dd_link_addtoend(Ddlist * end, Ddlist * el)

Add new element to the end of the list returning new end of the list.

List   *ref_addtoend(List * end, void *ptr, int type)

Ddlist *dd_ref_addtoend(Ddlist * end, void *ptr, int type)

Create a new element of given type referencing ptr and add it to the end of the list returning the new end of the list.

List   *list_addtoend(List * list, List * el) 

Ddlist *dd_list_addtoend(Ddlist * list, Ddlist * el)

Add new element to back of list returning the front of the new list. The list will actually only change at the initialisation of the list. These functions are easier to use but less efficient than the link_addtoend functions above.

void    link_addafter(List * at, List * el)  

void    dd_link_addafter(Ddlist * at, Ddlist * el)

Add new element el to the list after at.

List   *list_get_end(List * list)

Ddlist *dd_get_end(Ddlist * list)

Ddlist *dd_get_start(Ddlist * list)

Get start and end of a list from element el.

List   *link_get_by_ref(List * list, void *ptr)

List   *link_get_by_type(List * list, int type)

Ddlist *dd_link_get_by_ref(Ddlist * list, void *ptr)

Ddlist *dd_link_get_by_type(Ddlist * list, int type)

Get the first element in list referencing a given ptr or of a given type.

void    ref_free(List * at, void (*freefunc) ( /* ??? */ ))

void    dd_ref_free(Ddlist * at, void (*freefunc) ( /* ??? */ ))

Free the reference of the element el using freefunc and set the reference to NULL. The function freefunc is of the form

void freefunc(void *ptr, int type)

void    link_rm_next_el(List * at) 

List   *link_rm_el(List * at)

void    dd_link_rm_next_el(Ddlist * at)

Ddlist *dd_link_rm_el(Ddlist * at)

Functions for removing and freeing individual list elements. Note that link_rm_el results in a broken list which must be corrected (if required) by the user.

void    link_rm_next(List * at, void (*freefunc) ( /* ??? */ ))

List   *link_rm(List * at, void (*freefunc) ( /* ??? */ ))

void    dd_link_rm_next(Ddlist * at, void (*freefunc) ( /* ??? */ )) 

Ddlist *dd_link_rm(Ddlist * at, void (*freefunc) ( /* ??? */ ))

Functions to both remove a link and free up the reference. Again link_rm will result in a broken list. The function freefunc is of the form

void freefunc(void *ptr, int type)

   

void    list_rm_links(List * list) 

List   *list_rm_links_on_type(List * list, int type)

List   *list_rm_links_on_func(List * list, Bool(*func) ( /* ??? */ ),
                              void *data)

void    list_free_refs(List * list, void (*freefunc) ( /* ??? */ ))

void    list_rm(List * list, void (*freefunc) ())

void    dd_list_rm_links(Ddlist * list)

Ddlist *dd_list_rm_links_on_type(Ddlist * list, int type)

Ddlist *dd_list_rm_links_on_func(Ddlist * list, Bool(*func) ( /* ??? */ ))

void    dd_list_free_refs(Ddlist * list, void (*freefunc) ( /* ??? */ )) 

void    dd_list_rm(Ddlist * list, void (*freefunc) ( /* ??? */ ))

Various functions for freeing lists as a whole (predicated by type or a boolean function). The function freefunc is of the form

void freefunc(void *ptr, int type)

The function call in list_rm_links_on_func and dd_list_rm_links_on_func is of the form

Bool bool_func(void *ptr, int type)

List   *list_rm_el(List * list, List * el, void (*freefunc) ( /* ??? */ ))

List   *list_rm_ref(List * list, void *ptr, void (*freefunc) ( /* ??? */ ))

Ddlist *dd_list_rm_el(Ddlist * list, Ddlist * el, void (*freefunc) ( /* ??? */ )) 

Ddlist *dd_list_rm_ref(Ddlist * list, void *ptr, void (*freefunc) ( /* ??? */ ))

These functions simplify the situation (at some extra cost for singly directed lists), each removes an element from a list, repairs the list and returns it. For example, the function list_rm_el finds the element el in list and removes it and the object it references using freefunc. Similarly the function list_rm_ref is identical except that it locates the item to be deleted by the object it references rather than explicitly. The function freefunc is of the form

void freefunc(void *ptr, int type)

List   *link_copy(List * el, void *(*cpfunc) ( /* ??? */ ), void *data)

List   *list_copy(List * list, void *(*cpfunc) ( /* ??? */ ), void *data)

List   *list_reverse(List * list)

List   *list_reversecopy(List * list, void *(*cpfunc) ( /* ??? */ ), void *data)

Ddlist *dd_link_copy(Ddlist * el, void *(*cpfunc) ( /* ??? */ ), void *data)

Ddlist *dd_list_copy(Ddlist * list, void *(*cpfunc) ( /* ??? */ ), void *data)

Ddlist *dd_list_reverse(Ddlist * list)

For list copying and/or reversing. Where copy_func is of the form

void *copy_func(void *ptr, int type, void *data)

and a NULL copy function results in the generation of new link elements and/or lists which share reference data items with their originals.

void    list_apply_func(List * list, void (*func) ( /* ??? */ ), void *data)

void    dd_apply_func(Ddlist * list, void (*func) ( /* ??? */ ), void *data)

Apply function to elements of a list. Where func is of the form

void func(void *ptr, int type, void *data)

int list_length(List *list)

int dd_list_length(Ddlist *list)

Return the number of elements in a list.

List   *sort_list(List * list, double (*valfunc) ( /* ??? */ ), void *data)

Ddlist *sort_ddlist(Ddlist * list, double (*valfunc) ( /* ??? */ ), void *data)

Sort list into ascending order on the basis of applying valfunc to each data item, where valfunc is of the form

double valfunc(void* ptr, int type, void *data)