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

Macros
#define	SLIST_FWD 1

#define	SLIST_BWD -1

Typedefs
typedef struct SList_ *	Slist

typedef struct SListElmt_ *	SlistNode

typedef int(*	match_callback )(const void , const void )

Functions
Slist	SLISTinit (void(destroy)(void data))

void	SLISTdestroy (Slist list)

int	SLISTinsnext (Slist list, SlistNode node, const void *data)

int	SLISTremnext (Slist list, SlistNode node, void **data)

int	SLISTsize (Slist list)

SlistNode	SLISThead (Slist list)

SlistNode	SLISTtail (Slist list)

int	SLISTishead (Slist list, SlistNode node)

int	SLISTistail (Slist list, SlistNode node)

void *	SLISTdata (SlistNode node)

SlistNode	SLISTnext (SlistNode node)

SlistNode	SLISTfindnode (Slist list, const void *data)

void	SLISTsetmatch (Slist list, int(match)(const void key1, const void *key2))

match_callback	SLISTgetmatch (Slist list)

int	SLISTfind_remove (Slist list, void **data)

void	SLISTreverse (Slist list)

void	SLISTsort (Slist list, int(cmp)(const void key1, const void *key2))

void	SLISTtraverse (Slist list, void(callback)(const void data), int direction)

Macro Definition Documentation

#define SLIST_BWD -1

Macro for backward traversal of the list

Definition at line 58 of file slist.h.

#define SLIST_FWD 1

Macro for forward traversal of the list

Definition at line 53 of file slist.h.

Typedef Documentation

typedef int(* match_callback)(const void *, const void *)

Still another typedef - for creating a shorthand to a complex datatype - a pointer to a function, taking 2 parameters of type const void * - and returning an int.

Definition at line 80 of file slist.h.

typedef struct SList_* Slist

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

Definition at line 65 of file slist.h.

typedef struct SListElmt_* SlistNode

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

Definition at line 72 of file slist.h.

Function Documentation

void* SLISTdata ( SlistNode 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 179 of file slist.c.

void SLISTdestroy ( Slist list )

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 SLISTinit(), 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] list - a reference to current list.

Returns: Nothing.

See Also: SLISTinit()

Definition at line 71 of file slist.c.

int SLISTfind_remove	(	Slist	list,
		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, SLISTsetmatch().

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]	list	- 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: SLISTsetmatch()

Definition at line 206 of file slist.c.

SlistNode SLISTfindnode	(	Slist	list,
		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 - SLISTsetmatch().

Parameters

[in]	list	- 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: SLISTsetmatch()

Definition at line 189 of file slist.c.

match_callback SLISTgetmatch ( Slist list )

Get the stored match callback for searching the list

The call simply returns the the funtion reference to the match callback in the list header - formerly stored by the function SLISTsetmatch().

Parameters

[in] list - reference to current list.

Returns: The stored reference to a match callback function.

See Also: match_callback; SLISTsetmatch()

Definition at line 237 of file slist.c.

SlistNode SLISThead ( Slist list )

Get a reference to the head node of the list.

Parameters

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

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

Definition at line 159 of file slist.c.

Slist SLISTinit ( 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.

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: SLISTdestroy()

Definition at line 55 of file slist.c.

int SLISTinsnext	(	Slist	list,
		SlistNode	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 list. If you want to insert the new node at the beginning, the parameter node should be set to NULL.

Parameters

[in]	list	- reference to current list
[in]	node	- the node after which the new node is to be inserted. If set to NULL - the new node is inserted at the beginning.
[in]	data	- reference to data to be stored in the new node, that is inserted into the list.

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

Definition at line 85 of file slist.c.

int SLISTishead	(	Slist	list,
		SlistNode	node
	)

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

Parameters

[in]	list	- 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 169 of file slist.c.

int SLISTistail	(	Slist	list,
		SlistNode	node
	)

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

Parameters

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

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

Definition at line 174 of file slist.c.

SlistNode SLISTnext ( SlistNode 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 184 of file slist.c.

int SLISTremnext	(	Slist	list,
		SlistNode	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. If parameter node is set to NULL, then the first node in list will be removed. The caller is responsible for the future of this memory - deallocating it, for example.

Parameters

[in]	list	- 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 117 of file slist.c.

void SLISTreverse ( Slist list )

Reverse the list - physically.

Parameters

[in] list - reference to current list.

Returns: None.

Definition at line 242 of file slist.c.

void SLISTsetmatch	(	Slist	list,
		int()(const void key1, const void *key2)	match
	)

Set a valid match callback function for sequentially searching the list

Parameters

[in]	list	- 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 callback function shall return 1 - in case of a hit - or 0 otherwise.

Returns: Nothing.

Definition at line 232 of file slist.c.

int SLISTsize ( Slist list )

Get the list size.

Parameters

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

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

Definition at line 154 of file slist.c.

void SLISTsort	(	Slist	list,
		int()(const void key1, const void *key2)	cmp
	)

Sort a list according to the Selection Sort Algorithm - with complexity Θ(n²)).

Parameters

[in]	list	- reference to current list.
[in]	cmp	- reference to a user-defined callback function responsible for comparing node data. This callback function should return a value of -1 if data referenced by key1 is less than data referenced by key2 - or 0 if they are equal - or 1 otherwise. This will produce an ascending sort order. If a descending order is what you want - just swap the return values -1 and 1 for the comparisons made above.

Returns: Nothing.

Definition at line 270 of file slist.c.

SlistNode SLISTtail ( Slist list )

Get a reference to the tail node of the list.

Parameters

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

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

Definition at line 164 of file slist.c.

void SLISTtraverse	(	Slist	list,
		void()(const void data)	callback,
		int	direction
	)

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

Parameters

[in]	list	- 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.
[in]	direction	- direction of traversal. Set to SLIST_FWD for forward traversal - and SLIST_BWD for traversing backwards.

Returns: Nothing.

Definition at line 311 of file slist.c.

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation