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

slist.h File Reference

Singly-linked list. More...


Typedefs

typedef _SListEntry SListEntry
 Represents an entry in a singly-linked list.
typedef void(* SListIterator )(void *data, void *user_data)
 Callback function used for iterating over a list.
typedef int(* SListCompareFunc )(void *data1, void *data2)
 Callback function used to compare values in a list when sorting.
typedef int(* SListEqualFunc )(void *data1, void *data2)
 Callback function used to determine of two values in a list are equal.

Functions

void slist_free (SListEntry *list)
 Free an entire list.
SListEntryslist_prepend (SListEntry **list, void *data)
 Prepend data to the start of a list.
SListEntryslist_append (SListEntry **list, void *data)
 Append data to the end of a list.
SListEntryslist_next (SListEntry *listentry)
 Retrieve the next entry in a list.
void * slist_data (SListEntry *listentry)
 Retrieve the data at a list entry.
SListEntryslist_nth_entry (SListEntry *list, int n)
 Retrieve the entry at a specified index in a list.
void * slist_nth_data (SListEntry *list, int n)
 Retrieve the data at a specified entry in the list.
int slist_length (SListEntry *list)
 Find the length of a list.
void ** slist_to_array (SListEntry *list)
 Create a C array containing the contents of a list.
void slist_foreach (SListEntry *list, SListIterator callback, void *user_data)
 Iterate over all entries in a list.
int slist_remove_entry (SListEntry **list, SListEntry *entry)
 Remove an entry from a list.
int slist_remove_data (SListEntry **list, SListEqualFunc callback, void *data)
 Remove all occurrences of a particular piece of data from a list.
void slist_sort (SListEntry **list, SListCompareFunc compare_func)
 Sort a list.
SListEntryslist_find_data (SListEntry *list, SListEqualFunc callback, void *data)
 Find the entry for a particular data item in a list.


Detailed Description

Singly-linked list.

A singly-linked list stores a collection of values. Each entry in the list (represented by a pointer to a SListEntry structure) contains a link to the next entry. It is only possible to iterate over entries in a singly linked list in one direction.

To create a new singly-linked list, create a variable which is a pointer to a SListEntry, and initialise it to NULL.

To destroy a singly linked list, use slist_free.

To add new data at the start of a list, use slist_prepend. To add new data at the end of a list, use slist_append.

To find the length of a list, use slist_length.

To access data in a list by its index in the list, use slist_nth_data.

To search a list for data, use slist_find_data.

To sort a list into an order, use slist_sort.

To iterate over a list, use slist_foreach.

To find a particular entry in a list by its index, use slist_nth_entry.

Given a particular entry in a list:


Typedef Documentation

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

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

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 _SListEntry SListEntry
 

Represents an entry in a singly-linked list.

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

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

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

Returns:
A non-zero value if data1 and data2 are equal, zero if they are not equal.


Function Documentation

SListEntry* slist_append SListEntry **  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* slist_data SListEntry listentry  ) 
 

Retrieve the data at a list entry.

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

SListEntry* slist_find_data SListEntry list,
SListEqualFunc  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 slist_foreach SListEntry list,
SListIterator  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 slist_free SListEntry list  ) 
 

Free an entire list.

Parameters:
list The list to free.

int slist_length SListEntry list  ) 
 

Find the length of a list.

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

SListEntry* slist_next SListEntry listentry  ) 
 

Retrieve the next entry in a list.

Parameters:
listentry Pointer to the list entry.
Returns:
The next entry in the list.

void* slist_nth_data SListEntry 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.

SListEntry* slist_nth_entry SListEntry 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.

SListEntry* slist_prepend SListEntry **  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.

int slist_remove_data SListEntry **  list,
SListEqualFunc  callback,
void *  data
 

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

Parameters:
list Pointer to the list.
callback Callback function to invoke to compare data in the list with the data to remove.
data The data to remove from the list.
Returns:
The number of entries removed from the list.

int slist_remove_entry SListEntry **  list,
SListEntry 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 slist_sort SListEntry **  list,
SListCompareFunc  compare_func
 

Sort a list.

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

void** slist_to_array SListEntry 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 slist_length).


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