Generic Linked List

Data Structures
struct	ListEntry_s
	Structure used to hold an entry in a double linked list. More...
struct	List_s
	Structure describing a double linked list. More...
struct	ListIterator_s
	Structure to hold the state of a list iterator. More...
Defines
#define	ListIterator_Init(_iterator, _list)   (_iterator).current = (_list)->head, (_iterator).list = _list
	Initialise a ListIterator_t instance to point to the first entry in the list.
#define	ListIterator_Next(_iterator)   ((_iterator).current = ((_iterator).current?((_iterator).current->next):NULL))
	Move to the next entry.
#define	ListIterator_Current(_iterator)   ((_iterator).current->data)
	Retrieve the data stored at current entry.
#define	ListIterator_MoreEntries(_iterator)   ((_iterator).current)
	Determine whether there are any more entries in the list.
#define	ObjectListCreate()   ListCreate()
	Alias for ListCreate().
#define	ObjectListFree(list)   ListFree(list, ListFreeObject);
	Free a list that only contains objects.
#define	ListCount(_list)   (_list)->count
	Returns the number of entries in the specified list.
Typedefs
typedef struct ListEntry_s	ListEntry_t
typedef struct List_s	List_t
typedef struct ListIterator_s	ListIterator_t
typedef void(*	ListDataDestructor_t )(void *)
	Function pointer to a function to call with each entry->data in a list when the list is being freed.
Functions
List_t *	ListCreate ()
	Creates a new double linked list.
void	ListFree (List_t *list, void(*destructor)(void *data))
	Free a list and all the entries calling the destructor function for each entry.
void	ListFreeObject (void *ptr)
bool	ListAdd (List_t *list, void *data)
	Add an entry to the end of the list.
bool	ListRemove (List_t *list, void *data)
	Remove the first instance of data from the list.
bool	ListInsertBeforeCurrent (ListIterator_t *iterator, void *data)
	Insert an entry before the current entry in a list.
bool	ListInsertAfterCurrent (ListIterator_t *iterator, void *data)
	Insert an entry after the current entry in a list.
void	ListRemoveCurrent (ListIterator_t *iterator)
	Remove the current entry in the list pointed to by the iterator.
void	ListDump (List_t *list)
	Dump the structure of a list.

---

Define Documentation

#define ListCount

(

_list

)

(_list)->count

Returns the number of entries in the specified list.

Parameters:

_list

The list to retrieve the number of entries from.

Returns:

The number of entries in the list.

#define ListIterator_Current

(

_iterator

)

((_iterator).current->data)

Retrieve the data stored at current entry.

Parameters:

_iterator

The iterator to retrieve the data from.

Returns:

The data stored at the current entry.

#define ListIterator_Init	(	_iterator,
		_list		)	(_iterator).current = (_list)->head, (_iterator).list = _list

Initialise a ListIterator_t instance to point to the first entry in the list.

Example use of a ListIterator_t

 ListIterator_t iterator;
 for ( ListIterator_Init(iterator, list); ListIterator_MoreEntries(iterator); ListIterator_Next(iterator))
 {
    printf("Data = %p\n", ListIterator_Current(iterator));
 }

Parameters:

	_iterator	The iterator to initialise (not a pointer),
	_list	The list to initialise the iterator to use.

#define ListIterator_MoreEntries

(

_iterator

)

((_iterator).current)

Determine whether there are any more entries in the list.

Parameters:

_iterator

The iterator to test.

Returns:

True if there are more entries, false otherwise.

#define ListIterator_Next

(

_iterator

)

((_iterator).current = ((_iterator).current?((_iterator).current->next):NULL))

Move to the next entry.

Parameters:

_iterator

Iterator to update.

 

#define ObjectListCreate

(

)

ListCreate()

Alias for ListCreate().

Creates a list that will only be used to hold objects.

Returns:

A new List_t instance or NULL if there is not enough memory.

#define ObjectListFree

(

list

)

ListFree(list, ListFreeObject);

Free a list that only contains objects.

Any objects still in the list will have their reference counts decremented.

Parameters:

list

The list to free.

---

Function Documentation

bool ListAdd	(	List_t *	list,
		void *	data
	)

Add an entry to the end of the list.

Parameters:

	list	The list to add to.
	data	The data entry to add.

Returns:

TRUE if the data was added, false otherwise.

List_t* ListCreate

(

)

Creates a new double linked list.

Returns:

A new List_t instance or NULL if there is not enough memory.

void ListDump

(

List_t *

list

)

Dump the structure of a list.

Parameters:

list

the list to dump.

void ListFree	(	List_t *	list,
		void(*)(void *data)	destructor
	)

Free a list and all the entries calling the destructor function for each entry.

Parameters:

	list	The list to free.
	destructor	Function to call on each item in the list.

void ListFreeObject

(

void *

ptr

)

For internal use only.

Function used by the ObjectListFree() macro to decrement object ref counts.

bool ListInsertAfterCurrent	(	ListIterator_t *	iterator,
		void *	data
	)

Insert an entry after the current entry in a list.

Parameters:

	iterator	Current point in the list to insert the entry.
	data	The data to insert.

Returns:

TRUE if the data was added, false otherwise.

bool ListInsertBeforeCurrent	(	ListIterator_t *	iterator,
		void *	data
	)

Insert an entry before the current entry in a list.

Parameters:

	iterator	Current point in the list to insert the entry.
	data	The data to insert.

Returns:

TRUE if the data was added, false otherwise.

bool ListRemove	(	List_t *	list,
		void *	data
	)

Remove the first instance of data from the list.

Parameters:

	list	The list to remove the data from.
	data	The data to remove.

Returns:

true if the data was found.

void ListRemoveCurrent

(

ListIterator_t *

iterator

)

Remove the current entry in the list pointed to by the iterator.

After this function complete the iterator will point to the next entry in the list.

Parameters:

iterator

Iterator pointer to the current entry in the list to remove.