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.
SListEntry *	slist_prepend (SListEntry **list, void *data)
	Prepend data to the start of a list.
SListEntry *	slist_append (SListEntry **list, void *data)
	Append data to the end of a list.
SListEntry *	slist_next (SListEntry *listentry)
	Retrieve the next entry in a list.
void *	slist_data (SListEntry *listentry)
	Retrieve the data at a list entry.
SListEntry *	slist_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.
SListEntry *	slist_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:

• To find the next entry, use slist_next.
• To access the data stored at the entry, use slist_data.
• To remove the entry, use slist_remove_entry.

---

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).

---