libwget-list(3) Introduction to Library Functions libwget-list(3)

NAME

libwget-list - Circular doubly linked list

SYNOPSIS

Data Structures

struct wget_list_st

Typedefs

typedef struct wget_list_st wget_list

Functions

void * wget_list_append (wget_list **list, const void *data, size_t
size)
void * wget_list_prepend (wget_list **list, const void *data, size_t
size)
void wget_list_remove (wget_list **list, void *elem)
void * wget_list_getfirst (const wget_list *list)
void * wget_list_getlast (const wget_list *list)
void * wget_list_getnext (const void *elem)
int wget_list_browse (const wget_list *list, wget_list_browse_fn
*browse, void *context)
void wget_list_free (wget_list **list)

Detailed Description
Circular doubly linked lists provide fast insertion, removal and
iteration in either direction.

Each element has pointers to the next and the previous element.
Iteration can be done by calling the wget_list_browse() function, so
the list structure doesn't need to be exposed.

This datatype is used by the Wget2 tool to implement the job queue
(append and remove).

See wget_list_append() for an example on how to use lists.

Typedef Documentation
typedef struct wget_list_st wget_list
Type for double linked lists and list entries.

Function Documentation
void * wget_list_append (wget_list ** list, const void * data, size_t
size)
Parameters
list Pointer to Pointer to a circular doubly linked list
data Pointer to data to be inserted
size Size of data in bytes

Returns
Pointer to the new element or NULL if memory allocation failed

Append an element to the end of the list.
size bytes at data will be copied and appended to the list.

A pointer to the new element will be returned.

Note
The returned pointer must be freed by wget_list_remove() or
implicitly by wget_list_free().

Example:

wget_list *list = NULL;
struct mystruct mydata1 = { .x = 1, .y = 25 };
struct mystruct mydata2 = { .x = 5, .y = 99 };
struct mystruct *data;

wget_list_append(&list, &mydata1, sizeof(mydata1)); // append mydata1 to list
wget_list_append(&list, &mydata2, sizeof(mydata2)); // append mydata2 to list

data = wget_list_getfirst(list);
printf("data=(%d,%d)\n", data->x, data->y); // prints 'data=(1,25)'

wget_list_remove(&list, data);

data = wget_list_getfirst(list);
printf("data=(%d,%d)\n", data->x, data->y); // prints 'data=(5,99)'

wget_list_free(&list);

void * wget_list_prepend (wget_list ** list, const void * data, size_t
size)
Parameters
list Pointer to Pointer to a circular doubly linked list
data Pointer to data to be inserted
size Size of data in bytes

Returns
Pointer to the new element or NULL if memory allocation failed

Insert an entry at the beginning of the list. size bytes at data will
be copied and prepended to the list.

A pointer to the new element will be returned. It must be freed by
wget_list_remove() or implicitly by wget_list_free().

void wget_list_remove (wget_list ** list, void * elem)
Parameters
list Pointer to Pointer to a circular doubly linked list
elem Pointer to a list element returned by wget_list_append() or
wget_list_prepend()

Remove an element from the list.

void * wget_list_getfirst (const wget_list * list)
Parameters
list Pointer to a circular doubly linked list

Returns
Pointer to the first element of the list or NULL if the list is
empty

Get the first element of a list.

void * wget_list_getlast (const wget_list * list)
Parameters
list Pointer to a circular doubly linked list

Returns
Pointer to the last element of the list or NULL if the list is
empty

Get the last element of a list.

void * wget_list_getnext (const void * elem)
Parameters
elem Pointer to an element of a linked list

Returns
Pointer to the next element of the list or NULL if the list is
empty

Get the next element of a list.

int wget_list_browse (const wget_list * list, wget_list_browse_fn *
browse, void * context)
Parameters
list Pointer to a circular doubly linked list
browse Pointer to callback function which is called for every
element in the list. If the callback functions returns a value
not equal to zero, browsing is stopped and this value will be
returned by wget_list_browse.
context The context handle that will be passed to the callback
function

Returns
The return value of the last call to the browse function or -1 if
list is NULL (empty)

Iterate through all entries of the list and call the function browse
for each.

// assume that list contains C strings.
wget_list *list = NULL;

static int print_elem(void *context, const char *elem)
{
printf("%s\n",elem);
return 0;
}

void dump(WGET_LIST *list)
{
wget_list_browse(list, (wget_list_browse_t)print_elem, NULL);
}

void wget_list_free (wget_list ** list)
Parameters
list Pointer to Pointer to a circular doubly linked list

Freeing the list and it's entry.

Author
Generated automatically by Doxygen for wget2 from the source code.

wget2 Version 2.2.0 libwget-list(3)