A simple doubly-linked list implementation. More...

Files
file	doubly-linked_list.h
	A simple doubly-linked list implementation.

Classes
struct	dlList_node
	Node. More...
struct	dlList
	Doubly-linked list. More...

Enumerations
enum	dlList_returnValues { DLLIST_OK = 0, DLLIST_ERR_errArg, DLLIST_ERR_malloc, DLLIST_ERR_undefFunc }
	Return values. More...

Functions
void	dlList_init (struct dlList list, void(destroyFunction)(void data), int(compareFunction)(const void data1, const void data2), void (dataDeepCopyFunction)(const void *data))
	Initialise a doubly-linked list object.
void	dlList_destroy (struct dlList *list)
	Destroy a doubly-linked list.
int	dlList_insertBefore (struct dlList list, struct dlList_node beforeNode, void *data)
	Insert a new node before another node.
int	dlList_insertAfter (struct dlList list, struct dlList_node afterNode, void *data)
	Insert a new node after another node.
int	dlList_insertOrdered (struct dlList list, void data)
	Insert a new node in a sorted list.
int	dlList_append (struct dlList list, void data)
	Insert a new node at the end of a list.
int	dlList_remove (struct dlList list, struct dlList_node node, void **data)
	Remove a node from a list.
struct dlList_node *	dlList_find (const struct dlList list, const void key)
	Search for a node in a list.
struct dlList	dlList_copy (const struct dlList *list)
	Creates a duplicate of a list.
int	dlList_appendList (struct dlList list1, const struct dlList list2)
	Append one list to another.
void	dlList_sort (struct dlList *list)
	Sort a list.
size_t	dlList_size (const struct dlList *list)
	Number of nodes in list.
struct dlList_node *	dlList_first (const struct dlList *list)
	First node in list.
struct dlList_node *	dlList_last (const struct dlList *list)
	Last node in list.

Detailed Description

A simple doubly-linked list implementation.

Supports sorting and user-defined node deep-copy and destroy functions.

Class Documentation

struct dlList_node

Node.

Class Members
void *	data	User data.
struct dlList_node *	next	Pointer to next node.
struct dlList_node *	prev	Pointer to previous node.

Enumeration Type Documentation

enum dlList_returnValues

Return values.

Enumerator:

DLLIST_OK	Everything went fine.
DLLIST_ERR_errArg	An erroneous argument was passed to the function.
DLLIST_ERR_malloc	Memory allocation failed.
DLLIST_ERR_undefFunc	An undefined function pointer was attempted called.

Function Documentation

int dlList_append	(	struct dlList *	list,
		void *	data
	)

Insert a new node at the end of a list.

Parameters

list	doubly-linked list object
data	data to add to the new node

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL
DLLIST_ERR_malloc	if there was not enough memory to create a new node

int dlList_appendList	(	struct dlList *	list1,
		const struct dlList *	list2
	)

Append one list to another.

This function copies all data from one list to another. Deep data copy will be performed of user data if the user-supplied copy() function is defined.

Parameters

list1	list to append data to
list2	list to fetch data from

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL
DLLIST_ERR_malloc	if there was not enough memory to create a new node

struct dlList dlList_copy ( const struct dlList * list )

read

Creates a duplicate of a list.

This function uses copy(), if defined, to deep-copy user data.

Parameters

list	doubly-linked list object to copy

Returns: an exact copy of the given list, unless list is NULL, in which case an empty list is returned. If a memory allocation error occurs, an empty list is returned

void dlList_destroy ( struct dlList * list )

Destroy a doubly-linked list.

All nodes will be deleted, and destroy(), if defined, will be called on all user-supplised data

Parameters

list	doubly-linked list object

struct dlList_node* dlList_find	(	const struct dlList *	list,
		const void *	key
	)

read

Search for a node in a list.

The first node with data matching the given key will be return, or NULL if no node could be found.

Parameters

list	doubly-linked list object
key	data that will be compared to all node's data by using the user-supplied compare() function. Cannot be NULL

Returns: a node object if a node was found, or NULL if no node could be found. NULL will also be returned if any erroneous arguments was supplied or if compare() is undefined

void dlList_init	(	struct dlList *	list,
		void()(void data)	destroyFunction,
		int()(const void data1, const void *data2)	compareFunction,
		void ()(const void *data)	dataDeepCopyFunction
	)

Initialise a doubly-linked list object.

Parameters

list	doubly-linked list object
destroyFunction	pointer to a function that will be called whenever a node is destroyed. The supplied argument is the node data
compareFunction	pointer to a function that compares two instances of user data. It must return an integer less than, equal to, or greater than zero if the first argument is considered to be respectively less than, equal to or larger than the second
dataDeepCopyFunction	pointer to a function that creates a deep copy of user data. If NULL, data will be shared and not copied

int dlList_insertAfter	(	struct dlList *	list,
		struct dlList_node *	afterNode,
		void *	data
	)

Insert a new node after another node.

Insert a new node after the given node. The given node must exist if the list is non-empty.

Parameters

list	doubly-linked list object
afterNode	the node to insert the new node after
data	data to add to the new node

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL or if the list is non-empty and afterNode is NULL
DLLIST_ERR_malloc	if there was not enough memory to create a new node

int dlList_insertBefore	(	struct dlList *	list,
		struct dlList_node *	beforeNode,
		void *	data
	)

Insert a new node before another node.

Insert a new node before the given node. The given node must exist if the list is non-empty.

Parameters

list	doubly-linked list object
beforeNode	the node to insert the new node in front of
data	data to add to the new node

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL or if the list is non-empty and beforeNode is NULL
DLLIST_ERR_malloc	if there was not enough memory to create a new node

int dlList_insertOrdered	(	struct dlList *	list,
		void *	data
	)

Insert a new node in a sorted list.

The new node will be inserted so that the list will remain sorted by using the user-supplied compare() function. The compare() function must be defined.

Parameters

list	doubly-linked list object
data	data to add to the new node

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL
DLLIST_ERR_undefFunc	if compare() is undefined
DLLIST_ERR_malloc	if there was not enough memory to create a new node

int dlList_remove	(	struct dlList *	list,
		struct dlList_node *	node,
		void **	data
	)

Remove a node from a list.

Remove the given node, destroy user data if destroy() is defined and data is NULL. If data is non-NULL, the data from the node that is to be removed will be set to the given pointer.

Parameters

list	doubly-linked list object
node	node to remove. Must exist
pointer	to user data. If non-NULL, it will contain the user data of the node to remove. If NULL, and if destroy() is defined, user data will be destroyed by calling destroy( node->data )

Return values

DLLIST_OK	if no problems occurred
DLLIST_ERR_errArg	if list is NULL

void dlList_sort ( struct dlList * list )

Sort a list.

The user must have supplied a compare() function

Parameters

list	doubly-linked list object

Files

Classes

Enumerations

Functions

Detailed Description

Class Documentation

Enumeration Type Documentation

Function Documentation