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.