cctools
Data Structures | Functions
list.h File Reference

Double-linked non-intrusive list. More...

Go to the source code of this file.

Data Structures

struct  list_node
struct  list

Functions

struct listlist_create ()
 Create a new linked list.
struct listlist_duplicate (struct list *list)
 
Duplicate a linked list

Returns a copy of the linked list.

void list_delete (struct list *list)
 Delete a linked list.
void list_free (struct list *list)
 Free every item referred to by the list.
struct listlist_splice (struct list *top, struct list *bottom)
 Splice two lists together.
struct listlist_split (struct list *src, list_op_t cmp, const void *arg)
 
Split a list into two at the given item

If arg is NULL or not found, list_split returns NULL and the list is unaffected.

int list_size (struct list *list)
 Count the elements in a list.
int list_push_priority (struct list *list, void *item, int prio)
 Push an item in priority order.
int list_push_head (struct list *list, void *item)
 Push an item onto the list head.
void * list_pop_head (struct list *list)
 Pop an item off of the list head.
void * list_peek_head (struct list *list)
 Peek at the list head.
int list_push_tail (struct list *list, void *item)
 Push an item onto the list tail.
void * list_pop_tail (struct list *list)
 Pop an item off of the list tail.
void * list_peek_tail (struct list *list)
 Peek at the list tail.
void * list_find (struct list *list, list_op_t cmp, const void *arg)
 
Find an element within a list

This function searches the list, comparing each element in the list to arg, and returns a pointer to the first matching element.

void * list_remove (struct list *list, const void *value)
 
Remove an item from the list

This function searches the list for the item pointed to by value and removes it.

void list_first_item (struct list *list)
 Begin traversing a list.
void * list_next_item (struct list *list)
 Continue traversing a list.
int list_iterate (struct list *list, list_op_t op, const void *arg)
 Apply a function to a list.
int list_iterate_reverse (struct list *list, list_op_t op, const void *arg)
 Apply a function to a list in reverse.
struct listlist_sort (struct list *list, int(*comparator)(const void *, const void *))
 Sort a list using a comparator function.

Detailed Description

Double-linked non-intrusive list.

Function Documentation

struct list* list_create ( )
read

Create a new linked list.

Returns
A pointer to an empty linked list.
struct list* list_duplicate ( struct list list)
read

Duplicate a linked list

Returns a copy of the linked list.

Note that the pointers in both lists point to the same places.

Parameters
listThe list to be duplicated
Returns
A pointer to the duplicate list
void list_delete ( struct list list)

Delete a linked list.

Note that this function only deletes the list itself, it does not delete the items referred to by the list.

Parameters
listThe list to delete.
void list_free ( struct list list)

Free every item referred to by the list.

Note that this function does not delete the list itself.

Parameters
listThe list to free.
struct list* list_splice ( struct list top,
struct list bottom 
)
read

Splice two lists together.

Parameters
topA linked list that will be destroyed in the process.
bottomA linked list that will be destroyed in the process.
Returns
A new linked list with elements from top at the head and bottom at the tail.
struct list* list_split ( struct list src,
list_op_t  cmp,
const void *  arg 
)
read

Split a list into two at the given item

If arg is NULL or not found, list_split returns NULL and the list is unaffected.

Otherwise src will contain all elements [src->head, arg) and a new list will be created with all elements [arg, src->tail].

Parameters
srcThe linked list to be split
cmpThe comparison function. Should return non-zero on a match.
argThe data element to split on.
Returns
A new linked list with arg as the head and all elements after arg as elements of the new list.
int list_size ( struct list list)

Count the elements in a list.

Parameters
listThe list to count.
Returns
The number of items stored in the list.
int list_push_priority ( struct list list,
void *  item,
int  prio 
)

Push an item in priority order.

Parameters
listThe list to push onto.
itemThe item to push onto the list.
prioThe integer priority of the item.
Returns
True on success, false on failure (due to out of memory.)
int list_push_head ( struct list list,
void *  item 
)

Push an item onto the list head.

Parameters
listThe list to push onto.
itemThe item to push onto the list.
Returns
True on success, false on failure (due to out of memory.)
void* list_pop_head ( struct list list)

Pop an item off of the list head.

Parameters
listThe list to pop.
Returns
The item popped, or null if list is empty.
void* list_peek_head ( struct list list)

Peek at the list head.

Parameters
listThe list to peek.
Returns
The item at the list head, or null if list is empty.
int list_push_tail ( struct list list,
void *  item 
)

Push an item onto the list tail.

Parameters
listThe list to push onto.
itemThe item to push onto the list.
Returns
True on success, false on failure (due to out of memory.)
void* list_pop_tail ( struct list list)

Pop an item off of the list tail.

Parameters
listThe list to pop.
Returns
The item popped, or null if list is empty.
void* list_peek_tail ( struct list list)

Peek at the list tail.

Parameters
listThe list to peek.
Returns
The item at the list tail, or null if list is empty.
void* list_find ( struct list list,
list_op_t  cmp,
const void *  arg 
)

Find an element within a list

This function searches the list, comparing each element in the list to arg, and returns a pointer to the first matching element.

Parameters
listThe list to search
cmpThe comparison function. Should return non-zero on a match.
argThe element to compare against
Returns
A pointer to the first matched element, or NULL if no elements match.
void* list_remove ( struct list list,
const void *  value 
)

Remove an item from the list

This function searches the list for the item pointed to by value and removes it.

Parameters
listThe list to search
valueThe item to remove
Returns
The removed item.
void list_first_item ( struct list list)

Begin traversing a list.

This function sets the internal list iterator to the first item. Call list_next_item to begin returning the items.

Parameters
listThe list to traverse.
void* list_next_item ( struct list list)

Continue traversing a list.

This function returns the current list item, and advances the internal iterator to the next item.

Parameters
listThe list to traverse.
Returns
The current item in the list.
int list_iterate ( struct list list,
list_op_t  op,
const void *  arg 
)

Apply a function to a list.

Invokes op on every member of the list.

Parameters
listThe list to operate on.
opThe operator to apply.
argAn optional parameter to send to op.
int list_iterate_reverse ( struct list list,
list_op_t  op,
const void *  arg 
)

Apply a function to a list in reverse.

Invokes op on every member of the list in reverse.

Parameters
listThe list to operate on.
opThe operator to apply.
argAn optional parameter to send to op.
struct list* list_sort ( struct list list,
int(*)(const void *, const void *)  comparator 
)
read

Sort a list using a comparator function.

Parameters
listThe list to sort.
comparatorThe comparison function used in the sort. The function should take in pointers to two objects casted as void* and return an integer indicating whether the first is less than (negative), equal to (0), or greater than (positive) the second.
Returns
A pointer to the list passed in. Identical to the list parameter.