Main Page | Data Structures | File List | Data Fields | Globals

list.h File Reference

Doubly-linked list. More...


Typedefs

typedef _ListEntry ListEntry
 Represents an entry in a doubly-linked list.
typedef void(* ListIterator )(void *data, void *user_data)
 Callback function used for iterating over a list.
typedef int(* ListCompareFunc )(void *data1, void *data2)
 Callback function used to compare values in a list when sorting.
typedef int(* ListEqualFunc )(void *data1, void *data2)
 Callback function used to determine of two values in a list are equal.

Functions

void list_free (ListEntry *list)
 Free an entire list.
ListEntrylist_prepend (ListEntry **list, void *data)
 Prepend data to the start of a list.
ListEntrylist_append (ListEntry **list, void *data)
 Append data to the end of a list.
ListEntrylist_prev (ListEntry *listentry)
 Retrieve the previous entry in a list.
ListEntrylist_next (ListEntry *listentry)
 Retrieve the next entry in a list.
void * list_data (ListEntry *listentry)
 Retrieve the data at a list entry.
ListEntrylist_nth_entry (ListEntry *list, int n)
 Retrieve the entry at a specified index in a list.
void * list_nth_data (ListEntry *list, int n)
 Retrieve the data at a specified entry in the list.
int list_length (ListEntry *list)
 Find the length of a list.
void ** list_to_array (ListEntry *list)
 Create a C array containing the contents of a list.
void list_foreach (ListEntry *list, ListIterator callback, void *user_data)
 Iterate over all entries in a list.
int list_remove_entry (ListEntry **list, ListEntry *entry)
 Remove an entry from a list.
int list_remove_data (ListEntry **list, ListEqualFunc callback, void *data)
 Remove all occurrences of a particular piece of data from a list.
void list_sort (ListEntry **list, ListCompareFunc compare_func)
 Sort a list.
ListEntrylist_find_data (ListEntry *list, ListEqualFunc callback, void *data)
 Find the entry for a particular data item in a list.


Detailed Description

Doubly-linked list.

A doubly-linked list stores a collection of values. Each entry in the list (represented by a pointer a ListEntry structure) contains a link to the next entry and the previous entry. It is therefore possible to iterate over entries in the list in either direction.

To create an empty list, create a new variable which is a pointer to a ListEntry structure, and initialise it to NULL. To destroy an entire list, use list_free.

To add data to a list, use list_append or list_prepend.

To remove data from a list, use list_remove_entry or list_remove_data.

To iterate over entries in a list, use list_next and list_prev, along with the list_data function to access data.

To access an entry in the list by index, use list_nth_entry or list_nth_data.

To sort a list, use list_sort.


Typedef Documentation

typedef int(* ListCompareFunc)(void *data1, void *data2)
 

Callback function used to compare values in a list when sorting.

Parameters:
data1 The first value to compare.
data2 The second value to compare.
Returns:
A negative value if data1 should be sorted before data2, a positive value if data1 should be sorted after data2, zero if data1 and data2 are equal.

typedef struct _ListEntry ListEntry
 

Represents an entry in a doubly-linked list.

The empty list is represented by a NULL pointer. To initialise a new doubly linked list, simply create a variable of this type containing a pointer to NULL.

typedef int(* ListEqualFunc)(void *data1, void *data2)
 

Callback function used to determine of two values in a list are equal.

Parameters:
data1 The first value to compare.
data2 The second value to compare.
Returns:
A non-zero value if data1 and data2 are equal, zero if they are not equal.

typedef void(* ListIterator)(void *data, void *user_data)
 

Callback function used for iterating over a list.

Parameters:
data The element being iterated over.
user_data Extra data specified by the user.


Function Documentation

ListEntry* list_append ListEntry **  list,
void *  data
 

Append data to the end of a list.

Parameters:
list Pointer to the list to append to.
data Data to append.
Returns:
The new entry in the list.

void* list_data ListEntry listentry  ) 
 

Retrieve the data at a list entry.

Parameters:
listentry Pointer to the list entry.
Returns:
The data at the list entry.

ListEntry* list_find_data ListEntry list,
ListEqualFunc  callback,
void *  data
 

Find the entry for a particular data item in a list.

Parameters:
list The list to search.
callback Callback function to be invoked to determine if values are equal to the data to search for.
data The data to search for.
Returns:
The list entry of the item being searched for, or NULL if not found.

void list_foreach ListEntry list,
ListIterator  callback,
void *  user_data
 

Iterate over all entries in a list.

Parameters:
list The list.
callback Callback function to invoke for each entry in the list.
user_data Extra data to pass to the callback function.

void list_free ListEntry list  ) 
 

Free an entire list.

Parameters:
list The list to free.

int list_length ListEntry list  ) 
 

Find the length of a list.

Parameters:
list The list.
Returns:
The number of entries in the list.

ListEntry* list_next ListEntry listentry  ) 
 

Retrieve the next entry in a list.

Parameters:
listentry Pointer to the list entry.
Returns:
The next entry in the list, or NULL if this was the last entry in the list.

void* list_nth_data ListEntry list,
int  n
 

Retrieve the data at a specified entry in the list.

Parameters:
list The list.
n The index into the list .
Returns:
The data at the specified index, or NULL if unsuccessful.

ListEntry* list_nth_entry ListEntry list,
int  n
 

Retrieve the entry at a specified index in a list.

Parameters:
list The list.
n The index into the list .
Returns:
The entry at the specified index, or NULL if out of range.

ListEntry* list_prepend ListEntry **  list,
void *  data
 

Prepend data to the start of a list.

Parameters:
list Pointer to the list to prepend to.
data Data to prepend.
Returns:
The new entry in the list.

ListEntry* list_prev ListEntry listentry  ) 
 

Retrieve the previous entry in a list.

Parameters:
listentry Pointer to the list entry.
Returns:
The previous entry in the list, or NULL if this was the first entry in the list.

int list_remove_data ListEntry **  list,
ListEqualFunc  callback,
void *  data
 

Remove all occurrences of a particular piece of data from a list.

Parameters:
list Pointer to the list.
callback Function to invoke to compare data against the data to be removed.
data The data to remove from the list.
Returns:
The number of entries removed from the list.

int list_remove_entry ListEntry **  list,
ListEntry entry
 

Remove an entry from a list.

Parameters:
list Pointer to the list.
entry The list entry to remove .
Returns:
If the entry is not found in the list, returns zero, else returns non-zero.

void list_sort ListEntry **  list,
ListCompareFunc  compare_func
 

Sort a list.

Parameters:
list Pointer to the list to sort.
compare_func Function used to compare values in the list.

void** list_to_array ListEntry list  ) 
 

Create a C array containing the contents of a list.

Parameters:
list The list.
Returns:
A newly-allocated C array containing all values in the list. The length of the array is equal to the length of the list (see list_length).


Generated on Mon Jan 30 18:56:23 2006 for C Algorithms by  doxygen 1.4.4