list.h File Reference

Doubly-linked list. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	_ListIterator
	Definition of a ListIterator. More...

Macros
#define	LIST_NULL   ((void *) 0)
	A null ListValue. More...

Typedefs
typedef struct _ListEntry	ListEntry
	Represents an entry in a doubly-linked list. More...
typedef struct _ListIterator	ListIterator
	Structure used to iterate over a list. More...
typedef void *	ListValue
	A value stored in a list. More...
typedef int(*	ListCompareFunc) (ListValue value1, ListValue value2)
	Callback function used to compare values in a list when sorting. More...
typedef int(*	ListEqualFunc) (ListValue value1, ListValue value2)
	Callback function used to determine of two values in a list are equal. More...

Functions
void	list_free (ListEntry *list)
	Free an entire list. More...
ListEntry *	list_prepend (ListEntry **list, ListValue data)
	Prepend a value to the start of a list. More...
ListEntry *	list_append (ListEntry **list, ListValue data)
	Append a value to the end of a list. More...
ListEntry *	list_prev (ListEntry *listentry)
	Retrieve the previous entry in a list. More...
ListEntry *	list_next (ListEntry *listentry)
	Retrieve the next entry in a list. More...
ListValue	list_data (ListEntry *listentry)
	Retrieve the value at a list entry. More...
ListEntry *	list_nth_entry (ListEntry *list, int n)
	Retrieve the entry at a specified index in a list. More...
ListValue	list_nth_data (ListEntry *list, int n)
	Retrieve the value at a specified index in the list. More...
int	list_length (ListEntry *list)
	Find the length of a list. More...
ListValue *	list_to_array (ListEntry *list)
	Create a C array containing the contents of a list. More...
int	list_remove_entry (ListEntry **list, ListEntry *entry)
	Remove an entry from a list. More...
int	list_remove_data (ListEntry **list, ListEqualFunc callback, ListValue data)
	Remove all occurrences of a particular value from a list. More...
void	list_sort (ListEntry **list, ListCompareFunc compare_func)
	Sort a list. More...
ListEntry *	list_find_data (ListEntry *list, ListEqualFunc callback, ListValue data)
	Find the entry for a particular value in a list. More...
void	list_iterate (ListEntry **list, ListIterator *iter)
	Initialise a ListIterator structure to iterate over a list. More...
int	list_iter_has_more (ListIterator *iterator)
	Determine if there are more values in the list to iterate over. More...
ListValue	list_iter_next (ListIterator *iterator)
	Using a list iterator, retrieve the next value from the list. More...
void	list_iter_remove (ListIterator *iterator)
	Delete the current entry in the list (the value last returned from list_iter_next) More...

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.

Definition in file list.h.

Macro Definition Documentation

LIST_NULL

#define LIST_NULL   ((void *) 0)

A null ListValue.

Definition at line 95 of file list.h.

Typedef Documentation

ListCompareFunc

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.

Definition at line 106 of file list.h.

ListEntry

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.

Definition at line 1 of file list.h.

ListEqualFunc

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.

Definition at line 118 of file list.h.

ListIterator

typedef struct _ListIterator ListIterator

Structure used to iterate over a list.

Definition at line 1 of file list.h.

ListValue

typedef void* ListValue

A value stored in a list.

Definition at line 79 of file list.h.

Function Documentation

list_append()

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.

list_data()

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.

list_find_data()

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.

list_free()

void list_free

(

ListEntry *

list

)

Free an entire list.

Parameters

list	The list to free.

list_iter_has_more()

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.

list_iter_next()

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.

list_iter_remove()

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.

list_iterate()

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.

list_length()

int list_length

(

ListEntry *

list

)

Find the length of a list.

Parameters

list

The list.

Returns

The number of entries in the list.

list_next()

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.

list_nth_data()

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.

list_nth_entry()

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.

list_prepend()

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.

list_prev()

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.

list_remove_data()

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.

list_remove_entry()

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.

list_sort()

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.

list_to_array()

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