list.h File Reference

Doubly-linked list. More...

Data Structures

struct _ListIterator

Definition of a ListIterator. More...

Defines

#define LIST_NULL ((void *) 0)

A null ListValue.

Typedefs

typedef struct _ListEntry ListEntry

Represents an entry in a doubly-linked list.

typedef struct _ListIterator ListIterator

Structure used to iterate over a list.

typedef void * ListValue

A value stored in a list.

typedef int(* ListCompareFunc )(ListValue value1, ListValue value2)

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

typedef int(* ListEqualFunc )(ListValue value1, ListValue value2)

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

Functions

void list_free (ListEntry *list)

Free an entire list.

ListEntry * list_prepend (ListEntry **list, ListValue data)

Prepend a value to the start of a list.

ListEntry * list_append (ListEntry **list, ListValue data)

Append a value to the end of a list.

ListEntry * list_prev (ListEntry *listentry)

Retrieve the previous entry in a list.

ListEntry * list_next (ListEntry *listentry)

Retrieve the next entry in a list.

ListValue list_data (ListEntry *listentry)

Retrieve the value at a list entry.

ListEntry * list_nth_entry (ListEntry *list, int n)

Retrieve the entry at a specified index in a list.

ListValue list_nth_data (ListEntry *list, int n)

Retrieve the value at a specified index in the list.

int list_length (ListEntry *list)

Find the length of a list.

ListValue * list_to_array (ListEntry *list)

Create a C array containing the contents of a list.

int list_remove_entry (ListEntry **list, ListEntry *entry)

Remove an entry from a list.

int list_remove_data (ListEntry **list, ListEqualFunc callback, ListValue data)

Remove all occurrences of a particular value from a list.

void list_sort (ListEntry **list, ListCompareFunc compare_func)

Sort a list.

ListEntry * list_find_data (ListEntry *list, ListEqualFunc callback, ListValue data)

Find the entry for a particular value in a list.

void list_iterate (ListEntry **list, ListIterator *iter)

Initialise a ListIterator structure to iterate over a list.

int list_iter_has_more (ListIterator *iterator)

Determine if there are more values in the list to iterate over.

ListValue list_iter_next (ListIterator *iterator)

Using a list iterator, retrieve the next value from the list.

void list_iter_remove (ListIterator *iterator)

Delete the current entry in the list (the value last returned from list_iter_next).

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 a value to a list, use list_append or list_prepend.

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

To iterate over entries in a list, use list_iterate to initialise a ListIterator structure, with list_iter_next and list_iter_has_more to retrieve each value in turn. list_iter_remove can be used to remove the current entry.

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)(ListValue value1, ListValue value2)

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

Parameters:

	value1	The first value to compare.
	value2	The second value to compare.

Returns:: A negative value if value1 should be sorted before value2, a positive value if value1 should be sorted after value2, zero if value1 and value2 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)(ListValue value1, ListValue value2)

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

Parameters:

	value1	The first value to compare.
	value2	The second value to compare.

Returns:: A non-zero value if value1 and value2 are equal, zero if they are not equal.

Function Documentation

ListEntry* list_append	(	ListEntry **	list,
		ListValue	data
	)

Append a value to the end of a list.

Parameters:

	list	Pointer to the list to append to.
	data	The value to append.

Returns:: The new entry in the list, or NULL if it was not possible to allocate the memory for the new entry.

ListValue list_data ( ListEntry * listentry )

Retrieve the value at a list entry.

Parameters:

listentry

Pointer to the list entry.

Returns:: The value stored at the list entry.

ListEntry* list_find_data	(	ListEntry *	list,
		ListEqualFunc	callback,
		ListValue	data
	)

Find the entry for a particular value in a list.

Parameters:

	list	The list to search.
	callback	Function to invoke to compare values in the list with the value to be searched for.
	data	The value to search for.

Returns:: The list entry of the item being searched for, or NULL if not found.

void list_free ( ListEntry * list )

Free an entire list.

Parameters:

list

The list to free.

int list_iter_has_more ( ListIterator * iterator )

Determine if there are more values in the list to iterate over.

Parameters:

iterator

The list iterator.

Returns:: Zero if there are no more values in the list to iterate over, non-zero if there are more values to read.

ListValue list_iter_next ( ListIterator * iterator )

Using a list iterator, retrieve the next value from the list.

Parameters:

iterator

The list iterator.

Returns:: The next value from the list, or LIST_NULL if there are no more values in the list.

void list_iter_remove ( ListIterator * iterator )

Delete the current entry in the list (the value last returned from list_iter_next).

Parameters:

iterator

The list iterator.

void list_iterate	(	ListEntry **	list,
		ListIterator *	iter
	)

Initialise a ListIterator structure to iterate over a list.

Parameters:

	list	A pointer to the list to iterate over.
	iter	A pointer to an iterator structure to initialise.

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.

ListValue list_nth_data	(	ListEntry *	list,
		int	n
	)

Retrieve the value at a specified index in the list.

Parameters:

	list	The list.
	n	The index into the list.

Returns:: The value at the specified index, or LIST_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,
		ListValue	data
	)

Prepend a value to the start of a list.

Parameters:

	list	Pointer to the list to prepend to.
	data	The value to prepend.

Returns:: The new entry in the list, or NULL if it was not possible to allocate the memory for the new entry.

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,
		ListValue	data
	)

Remove all occurrences of a particular value from a list.

Parameters:

	list	Pointer to the list.
	callback	Function to invoke to compare values in the list with the value to be removed.
	data	The value 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.

ListValue* 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, or NULL if it was not possible to allocate the memory. The length of the array is equal to the length of the list (see list_length).


Data Structures
struct	_ListIterator
	Definition of a ListIterator. More...
Defines
#define	LIST_NULL ((void *) 0)
	A null ListValue.
Typedefs
typedef struct _ListEntry	ListEntry
	Represents an entry in a doubly-linked list.
typedef struct _ListIterator	ListIterator
	Structure used to iterate over a list.
typedef void *	ListValue
	A value stored in a list.
typedef int(*	ListCompareFunc )(ListValue value1, ListValue value2)
	Callback function used to compare values in a list when sorting.
typedef int(*	ListEqualFunc )(ListValue value1, ListValue value2)
	Callback function used to determine of two values in a list are equal.
Functions
void	list_free (ListEntry *list)
	Free an entire list.
ListEntry *	list_prepend (ListEntry **list, ListValue data)
	Prepend a value to the start of a list.
ListEntry *	list_append (ListEntry **list, ListValue data)
	Append a value to the end of a list.
ListEntry *	list_prev (ListEntry *listentry)
	Retrieve the previous entry in a list.
ListEntry *	list_next (ListEntry *listentry)
	Retrieve the next entry in a list.
ListValue	list_data (ListEntry *listentry)
	Retrieve the value at a list entry.
ListEntry *	list_nth_entry (ListEntry *list, int n)
	Retrieve the entry at a specified index in a list.
ListValue	list_nth_data (ListEntry *list, int n)
	Retrieve the value at a specified index in the list.
int	list_length (ListEntry *list)
	Find the length of a list.
ListValue *	list_to_array (ListEntry *list)
	Create a C array containing the contents of a list.
int	list_remove_entry (ListEntry *list, ListEntry entry)
	Remove an entry from a list.
int	list_remove_data (ListEntry **list, ListEqualFunc callback, ListValue data)
	Remove all occurrences of a particular value from a list.
void	list_sort (ListEntry **list, ListCompareFunc compare_func)
	Sort a list.
ListEntry *	list_find_data (ListEntry *list, ListEqualFunc callback, ListValue data)
	Find the entry for a particular value in a list.
void	list_iterate (ListEntry *list, ListIterator iter)
	Initialise a ListIterator structure to iterate over a list.
int	list_iter_has_more (ListIterator *iterator)
	Determine if there are more values in the list to iterate over.
ListValue	list_iter_next (ListIterator *iterator)
	Using a list iterator, retrieve the next value from the list.
void	list_iter_remove (ListIterator *iterator)
	Delete the current entry in the list (the value last returned from list_iter_next).