wget2: Circular doubly linked list

| wget2 2.2.1

Loading...
Searching...
No Matches
Circular doubly linked list

## 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

## ◆ wget_list

typedef struct wget_list_st wget_list

Type for double linked lists and list entries.

## Function Documentation

## ◆ wget_list_append()

void * wget_list_append | ( | wget_list ** | list,
|  | const void * | data,
|  | size_t | size )

Parameters

  [in] | list | Pointer to Pointer to a circular doubly linked list
  [in] | data | Pointer to data to be inserted
  [in] | 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);
wget_list_append
WGETAPI void *NULLABLE wget_list_append(wget_list **list, const void *data, size_t size) WGET_GCC_NONNULL_ALL
Definition list.c:96
wget_list_remove
WGETAPI void wget_list_remove(wget_list **list, void *elem) WGET_GCC_NONNULL_ALL
Definition list.c:147
wget_list_free
WGETAPI void wget_list_free(wget_list **list) WGET_GCC_NONNULL_ALL
Definition list.c:249
wget_list
struct wget_list_st wget_list
Definition wget.h:405
wget_list_getfirst
WGETAPI void *NULLABLE wget_list_getfirst(const wget_list *list) WGET_GCC_CONST
Definition list.c:172

## ◆ wget_list_prepend()

void * wget_list_prepend | ( | wget_list ** | list,
|  | const void * | data,
|  | size_t | size )

Parameters

  [in] | list | Pointer to Pointer to a circular doubly linked list
  [in] | data | Pointer to data to be inserted
  [in] | 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().

## ◆ wget_list_remove()

void wget_list_remove | ( | wget_list ** | list,
|  | void * | elem )

Parameters

  [in] | list | Pointer to Pointer to a circular doubly linked list
  [in] | elem | Pointer to a list element returned by wget_list_append() or wget_list_prepend()

Remove an element from the list.

## ◆ wget_list_getfirst()

void * wget_list_getfirst | ( | const wget_list * | list | ) |

Parameters

  [in] | 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.

## ◆ wget_list_getlast()

void * wget_list_getlast | ( | const wget_list * | list | ) |

Parameters

  [in] | 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.

## ◆ wget_list_getnext()

void * wget_list_getnext | ( | const void * | elem | ) |

Parameters

  [in] | 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.

## ◆ wget_list_browse()

int wget_list_browse | ( | const wget_list * | list,
|  | wget_list_browse_fn * | browse,
|  | void * | context )

Parameters

  [in] | list | Pointer to a circular doubly linked list
  [in] | 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.
  [in] | 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);
}
wget_list_browse
WGETAPI int wget_list_browse(const wget_list *list, wget_list_browse_fn *browse, void *context) WGET_GCC_NONNULL((2))
Definition list.c:230

## ◆ wget_list_free()

void wget_list_free | ( | wget_list ** | list | ) |

Parameters

  [in] | list | Pointer to Pointer to a circular doubly linked list

Freeing the list and it's entry.