list.h File Reference


Detailed Description

Double-linked non-intrusive list.

Go to the source code of this file.

Data Structures

struct  list_node
struct  list

Functions

list * list_create ()
 Create a new linked list.
list * list_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.
list * list_splice (struct list *top, struct list *bottom)
 Splice two lists together.
list * list_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.
list * list_sort (struct list *list, int(*comparator)(const void *, const void *))
 Sort a list using a comparator function.


Function Documentation

struct list* list_create (  ) 

Create a new linked list.

Returns:
A pointer to an empty linked list.

struct list* list_duplicate ( struct list *  list  ) 

Duplicate a linked list Returns a copy of the linked list.

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

Parameters:
list The 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:
list The 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:
list The list to free.

struct list* list_splice ( struct list *  top,
struct list *  bottom 
)

Splice two lists together.

Parameters:
top A linked list that will be destroyed in the process.
bottom A 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 
)

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:
src The linked list to be split
cmp The comparison function. Should return non-zero on a match.
arg The 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:
list The 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:
list The list to push onto.
item The item to push onto the list.
prio The 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:
list The list to push onto.
item The 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:
list The 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:
list The 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:
list The list to push onto.
item The 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:
list The 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:
list The 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:
list The list to search
cmp The comparison function. Should return non-zero on a match.
arg The 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:
list The list to search
value The 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:
list The 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:
list The 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:
list The list to operate on.
op The operator to apply.
arg An 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:
list The list to operate on.
op The operator to apply.
arg An optional parameter to send to op.

struct list* list_sort ( struct list *  list,
int(*)(const void *, const void *)  comparator 
)

Sort a list using a comparator function.

Parameters:
list The list to sort.
comparator The 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.


Generated on Wed Oct 19 14:38:48 2011 for cctools by  doxygen 1.4.7