#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <malloc.h>
#include <assert.h>

Typedefs
typedef struct CSList_ *	CSlist

typedef struct CSListElmt_ *	CSlistNode

Functions
CSlist	CSLISTinit (void(destroy)(void data))

void	CSLISTdestroy (CSlist clist)

int	CSLISTinsnext (CSlist clist, CSlistNode node, const void *data)

int	CSLISTremnext (CSlist clist, CSlistNode node, void **data)

int	CSLISTsize (CSlist clist)

CSlistNode	CSLISThead (CSlist clist)

int	CSLISTishead (CSlist clist, CSlistNode node)

void *	CSLISTdata (CSlistNode node)

CSlistNode	CSLISTnext (CSlistNode node)

CSlistNode	CSLISTfindnode (CSlist clist, const void *data)

void	CSLISTsetmatch (CSlist clist, int(match)(const void key1, const void *key2))

int	CSLISTfind_remove (CSlist clist, void **data)

void	CSLISTtraverse (CSlist clist, void(callback)(const void data))

Typedef Documentation

typedef struct CSList_* CSlist

Use a typedef - to hide the interior of CSList_ - in the implementation file. This is how data hiding can be done in C.

Definition at line 43 of file cslist.h.

typedef struct CSListElmt_* CSlistNode

Another typedef - for hiding the interior of CSListElmt_ - in the implementation file.

Definition at line 50 of file cslist.h.

Function Documentation

void* CSLISTdata ( CSlistNode node )

Get a reference to data stored in a node.

Parameters

[in] node - a reference to the current node.

Returns: Generic reference to data - stored in parameter node.

Definition at line 153 of file cslist.c.

void CSLISTdestroy ( CSlist clist )

Destroy the list.

The list is destroyed - that is, all the memory occupied by the nodes is deallocated. The user-defined callback function destroy, given as an argument to CSLISTinit(), is responsible for freeing dynamically allocated node data, when this function is called. When all nodes and data have been deallocated - the list header is deallocated, too.

Parameters

[in] clist - a reference to current list.

Returns: Nothing.

See Also: CSLISTinit()

Definition at line 59 of file cslist.c.

int CSLISTfind_remove	(	CSlist	clist,
		void **	data
	)

Search - and remove a node - by using an in/out parameter.

When called, the 2nd parameter of this function, data, should reference a pointer, that points to the search key data. Moreover, a user-defined callback function responsible for doing the matching of node data - and data referenced by parameter data - must exist for this function to work - otherwise -2 will be returned - always. This user-supplied match-callback is set into the list with a call to another function, CSLISTsetmatch().

After the call - an (external) pointer referenced by parameter data, has been redirected to point to data of the removed node - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters

[in]	clist	- reference to current list.
[in,out]	data	- reference to an external pointer, that initially shall point to the search key data - when this function is called. After the call, this referenced (external) pointer, has been redirected - to point to node data of the removed node - if the call was successful. The caller is responsible for the future of this memory - deallocating it, for example.

Returns: Value 0 – if the call was OK - that is, node found and removed.
Value 1 – node not found.
Value -2 – if match-callback is not set.
Value -1 – otherwise (implies fatal error).

See Also: CSLISTsetmatch()

Definition at line 197 of file cslist.c.

CSlistNode CSLISTfindnode	(	CSlist	clist,
		const void *	data
	)

Find the first node - with node data matching data referenced by parameter data.

Search the list sequentially for a node, whose data matches the data referenced by parameter data. A reference to the node with the first match will be returned - NULL otherwise. A user-defined callback function, responsible for doing the matching of node data - with data referenced by parameter data - must exist for this function to work - otherwise NULL will be returned - always. This user-supplied match-callback is set into the list with another function - CSLISTsetmatch().

Parameters

[in]	clist	- reference to the current list.
[in]	data	- reference to the search key data.

Returns: Reference to the first node with a match to data referenced by parameter data - if found - NULL otherwise

See Also: CSLISTsetmatch()

Definition at line 163 of file cslist.c.

CSlistNode CSLISThead ( CSlist clist )

Get a reference to the head node of the list.

Parameters

[in] clist - a reference to the current list.

Returns: A reference to the first node in the list.

Definition at line 143 of file cslist.c.

CSlist CSLISTinit ( void(*)(void *data) destroy )

Initiate the list.

Parameters

[in] destroy - A reference to a user-made function, reponsible for freeing node data, when the list is deleted. If destroy is NULL - then node data will be left untouched when the list is destroyed. This function has a lot in common with SLISTinit().

Returns: A reference - to a new, empty list - if dynamic memory allocation for the ADT was successful - or NULL otherwise. Take really good care of this return value, since it will be needed as a parameter in subsequent calls - to the majority of other list handling functions in this function interface - i.e. a sort of "handle" to the list.

See Also: CSLISTdestroy(), SLISTinit()

Definition at line 44 of file cslist.c.

int CSLISTinsnext	(	CSlist	clist,
		CSlistNode	node,
		const void *	data
	)

Insert a new node - after parameter node - into the list.

This function inserts an new node, with a reference to node data given by parameter data - after the node referenced by parameter node - into clist.

Parameters

[in]	clist	- reference to current circular list
[in]	node	- the node after which the new node is to be inserted. When inserting a node into an empty list, node may hold any value - but should be set to NULL - just to avoid confusion.
[in]	data	- reference to data to be stored in the new node, that is inserted into the circular list.

Returns: Value 0 - if everything went OK - or value -1 otherwise.

Definition at line 72 of file cslist.c.

int CSLISTishead	(	CSlist	clist,
		CSlistNode	node
	)

Determine if a certain node is the head node of the list - or not.

Parameters

[in]	clist	- a reference to the current list.
[in]	node	- a reference to the node to be tested.

Returns: Value 1 - if node indeed is the first node of the list - or 0 otherwise.

Definition at line 148 of file cslist.c.

CSlistNode CSLISTnext ( CSlistNode node )

Get a reference to the next node in the list.

Parameters

[in] node - a reference to current node.

Returns: A reference to the next node - following parameter node - in the list.

Definition at line 158 of file cslist.c.

int CSLISTremnext	(	CSlist	clist,
		CSlistNode	node,
		void **	data
	)

Remove the node - directly after - parameter node.

After the call - an (external) pointer referenced by parameter data, has been redirected to point to data of the removed node - if the call was succesful. The caller is responsible for the future of this memory - deallocating it, if needed, for example.

Parameters

[in]	clist	- reference to current list.
[in]	node	- the node just before the node to be removed.
[out]	data	- reference to a pointer, that will point to data of the removed node - after the call, if successful.

Returns: Value 0 - if everything went OK - or value -1 otherwise.

Definition at line 101 of file cslist.c.

void CSLISTsetmatch	(	CSlist	clist,
		int()(const void key1, const void *key2)	match
	)

Set a valid match callback function for sequentially searching the list

Parameters

[in]	clist	- reference to current list.
[in]	match	- a reference to a user-defined function that receives references to node data - and search key data - via its parameters key1 and key2 - and thereby can make the actual matching. This user-defined callback function shall return 1 - in case of a hit - or 0 otherwise.

Returns: Nothing.

Definition at line 192 of file cslist.c.

int CSLISTsize ( CSlist clist )

Get the list size.

Parameters

[in] clist - a reference to the current list.

Returns: The size, that is, the number of nodes in the list.

Definition at line 138 of file cslist.c.

void CSLISTtraverse	(	CSlist	clist,
		void()(const void data)	callback
	)

Traverse the list from the beginning - and have a user-defined function called - for each node in the list.

Parameters

[in]	clist	- reference to current list.
[in]	callback	- reference to user-defined callback function, that gets read access to node data via its parameter data - to do whatever is relevant. Print data, for example.

Returns: Nothing.

Definition at line 247 of file cslist.c.

Typedefs

Functions

Typedef Documentation

Function Documentation