list

The list data type implements a fast generic doubly-linked list. More...

Typedefs
typedef struct stp_list_item	stp_list_item_t
	The list item opaque data type. More...
typedef struct stp_list	stp_list_t
	The list opaque data type. More...
typedef void(*	stp_node_freefunc) (void *)
	A callback function to free the data a node contains. More...
typedef void *(*	stp_node_copyfunc) (const void *)
	A callback function to copy the data a node contains. More...
typedef const char *(*	stp_node_namefunc) (const void *)
	A callback function to get the name of a node. More...
typedef int(*	stp_node_sortfunc) (const void *, const void *)
	A callback function to compare two nodes. More...

Functions
void	stp_list_node_free_data (void *item)
	Free node data allocated with stp_malloc. More...
stp_list_t *	stp_list_create (void)
	Create a new list object. More...
stp_list_t *	stp_list_copy (const stp_list_t *list)
	Copy and allocate a list object. More...
int	stp_list_destroy (stp_list_t *list)
	Destroy a list object. More...
stp_list_item_t *	stp_list_get_start (const stp_list_t *list)
	Find the first item in a list. More...
stp_list_item_t *	stp_list_get_end (const stp_list_t *list)
	Find the last item in a list. More...
stp_list_item_t *	stp_list_get_item_by_index (const stp_list_t *list, int idx)
	Find an item in a list by its index. More...
stp_list_item_t *	stp_list_get_item_by_name (const stp_list_t *list, const char *name)
	Find an item in a list by its name. More...
stp_list_item_t *	stp_list_get_item_by_long_name (const stp_list_t *list, const char *long_name)
	Find an item in a list by its long name. More...
int	stp_list_get_length (const stp_list_t *list)
	Get the length of a list. More...
void	stp_list_set_freefunc (stp_list_t *list, stp_node_freefunc freefunc)
	Set a list node free function. More...
stp_node_freefunc	stp_list_get_freefunc (const stp_list_t *list)
	Get a list node free function. More...
void	stp_list_set_copyfunc (stp_list_t *list, stp_node_copyfunc copyfunc)
	Set a list node copy function. More...
stp_node_copyfunc	stp_list_get_copyfunc (const stp_list_t *list)
	Get a list node copy function. More...
void	stp_list_set_namefunc (stp_list_t *list, stp_node_namefunc namefunc)
	Set a list node name function. More...
stp_node_namefunc	stp_list_get_namefunc (const stp_list_t *list)
	Get a list node name function. More...
void	stp_list_set_long_namefunc (stp_list_t *list, stp_node_namefunc long_namefunc)
	Set a list node long name function. More...
stp_node_namefunc	stp_list_get_long_namefunc (const stp_list_t *list)
	Get a list node long name function. More...
void	stp_list_set_sortfunc (stp_list_t *list, stp_node_sortfunc sortfunc)
	Set a list node sort function. More...
stp_node_sortfunc	stp_list_get_sortfunc (const stp_list_t *list)
	Get a list node sort function. More...
int	stp_list_item_create (stp_list_t *list, stp_list_item_t *next, const void *data)
	Create a new list item. More...
int	stp_list_item_destroy (stp_list_t *list, stp_list_item_t *item)
	Destroy a list item. More...
stp_list_item_t *	stp_list_item_prev (const stp_list_item_t *item)
	Get the previous item in the list. More...
stp_list_item_t *	stp_list_item_next (const stp_list_item_t *item)
	Get the next item in the list. More...
void *	stp_list_item_get_data (const stp_list_item_t *item)
	Get the data associated with a list item. More...
int	stp_list_item_set_data (stp_list_item_t *item, void *data)
	Set the data associated with a list item. More...

Detailed Description

The list data type implements a fast generic doubly-linked list.

It supports all of the operations you might want in a list (insert, remove, iterate over the list, copy whole lists), plus some (optional) less common features: finding items by index, name or long name, and sorting. These should also be fairly fast, due to caching in the list head.

Typedef Documentation

stp_list_item_t

typedef struct stp_list_item stp_list_item_t

The list item opaque data type.

This object is a node in the list.

stp_list_t

typedef struct stp_list stp_list_t

The list opaque data type.

This object represents the list as a whole.

stp_node_copyfunc

typedef void*(* stp_node_copyfunc) (const void *)

A callback function to copy the data a node contains.

The parameter is a pointer to the node data. The return value is a pointer to the new copy of the data.

stp_node_freefunc

typedef void(* stp_node_freefunc) (void *)

A callback function to free the data a node contains.

The parameter is a pointer to the node data.

stp_node_namefunc

typedef const char*(* stp_node_namefunc) (const void *)

A callback function to get the name of a node.

The parameter is a pointer to the node data. The return value is a pointer to the name of the node, or NULL if there is no name.

stp_node_sortfunc

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

A callback function to compare two nodes.

The two parameters are pointers to node data. The return value is <0 if the first sorts before the second, 0 if they sort identically, and >0 if the first sorts after the second.

Function Documentation

stp_list_copy()

stp_list_t* stp_list_copy

(

const stp_list_t *

list

)

Copy and allocate a list object.

list must be a valid list object previously created with stp_list_create().

Parameters

list	the list to copy.

Returns

a pointer to the new copy of the list.

stp_list_create()

stp_list_t* stp_list_create

(

void

)

Create a new list object.

Returns

the newly created list object.

stp_list_destroy()

int stp_list_destroy

(

stp_list_t *

list

)

Destroy a list object.

It is an error to destroy the list more than once.

Parameters

list	the list to destroy.

Returns

0 on success, 1 on failure.

stp_list_get_copyfunc()

stp_node_copyfunc stp_list_get_copyfunc

(

const stp_list_t *

list

)

Get a list node copy function.

Parameters

list	the list to use.

Returns

the function previously set with stp_list_set_copyfunc, or NULL if no function has been set.

stp_list_get_end()

stp_list_item_t* stp_list_get_end

(

const stp_list_t *

list

)

Find the last item in a list.

Parameters

list	the list to use.

Returns

a pointer to the last list item, or NULL if the list is empty.

stp_list_get_freefunc()

stp_node_freefunc stp_list_get_freefunc

(

const stp_list_t *

list

)

Get a list node free function.

Parameters

list	the list to use.

Returns

the function previously set with stp_list_set_freefunc, or NULL if no function has been set.

stp_list_get_item_by_index()

stp_list_item_t* stp_list_get_item_by_index	(	const stp_list_t *	list,
		int	idx
	)

Find an item in a list by its index.

Parameters

list	the list to use.
idx	the index to find.

Returns

a pointer to the list item, or NULL if the index is invalid or the list is empty.

stp_list_get_item_by_long_name()

stp_list_item_t* stp_list_get_item_by_long_name	(	const stp_list_t *	list,
		const char *	long_name
	)

Find an item in a list by its long name.

Parameters

list	the list to use.
long_name	the long name to find.

Returns

a pointer to the list item, or NULL if the long name is invalid or the list is empty.

stp_list_get_item_by_name()

stp_list_item_t* stp_list_get_item_by_name	(	const stp_list_t *	list,
		const char *	name
	)

Find an item in a list by its name.

Parameters

list	the list to use.
name	the name to find.

Returns

a pointer to the list item, or NULL if the name is invalid or the list is empty.

stp_list_get_length()

int stp_list_get_length

(

const stp_list_t *

list

)

Get the length of a list.

Parameters

list	the list to use.

Returns

the list length (number of list items).

stp_list_get_long_namefunc()

stp_node_namefunc stp_list_get_long_namefunc

(

const stp_list_t *

list

)

Get a list node long name function.

Parameters

list	the list to use.

Returns

the function previously set with stp_list_set_long_namefunc, or NULL if no function has been set.

stp_list_get_namefunc()

stp_node_namefunc stp_list_get_namefunc

(

const stp_list_t *

list

)

Get a list node name function.

Parameters

list	the list to use.

Returns

the function previously set with stp_list_set_namefunc, or NULL if no function has been set.

stp_list_get_sortfunc()

stp_node_sortfunc stp_list_get_sortfunc

(

const stp_list_t *

list

)

Get a list node sort function.

Parameters

list	the list to use.

Returns

the function previously set with stp_list_set_sortfunc, or NULL if no function has been set.

stp_list_get_start()

stp_list_item_t* stp_list_get_start

(

const stp_list_t *

list

)

Find the first item in a list.

Parameters

list	the list to use.

Returns

a pointer to the first list item, or NULL if the list is empty.

stp_list_item_create()

int stp_list_item_create	(	stp_list_t *	list,
		stp_list_item_t *	next,
		const void *	data
	)

Create a new list item.

Parameters

list	the list to use.
next	the next item in the list, or NULL to insert at the end of the list.
data	the data the list item will contain.

Returns

0 on success, 1 on failure (if data is NULL, for example).

stp_list_item_destroy()

int stp_list_item_destroy	(	stp_list_t *	list,
		stp_list_item_t *	item
	)

Destroy a list item.

Parameters

list	the list to use.
item	the item to destroy.

Returns

0 on success, 1 on failure.

stp_list_item_get_data()

void* stp_list_item_get_data

(

const stp_list_item_t *

item

)

Get the data associated with a list item.

Parameters

item	the list item to use.

Returns

the data associated with item.

stp_list_item_next()

stp_list_item_t* stp_list_item_next

(

const stp_list_item_t *

item

)

Get the next item in the list.

Parameters

item	the item to start from.

Returns

a pointer to the list item following from item, or NULL if item is the end of the list.

stp_list_item_prev()

stp_list_item_t* stp_list_item_prev

(

const stp_list_item_t *

item

)

Get the previous item in the list.

Parameters

item	the item to start from.

Returns

a pointer to the list item prior to item, or NULL if item is the start of the list.

stp_list_item_set_data()

int stp_list_item_set_data	(	stp_list_item_t *	item,
		void *	data
	)

Set the data associated with a list item.

Warning

Note that if a sortfunc is in use, changing the data will NOT re-sort the list!

Parameters

item	the list item to use.
data	the data to set.

Returns

0 on success, 1 on failure (if data is NULL).

stp_list_node_free_data()

void stp_list_node_free_data

(

void *

item

)

Free node data allocated with stp_malloc.

This function is indended for use as an stp_node_freefunc, which uses stp_free to free the node data.

Parameters

item	the node data to free

stp_list_set_copyfunc()

void stp_list_set_copyfunc	(	stp_list_t *	list,
		stp_node_copyfunc	copyfunc
	)

Set a list node copy function.

This callback function will be called whenever a list item is copied. Its intended use is for automatic object copying (since C lacks a copy constructor).

Parameters

list	the list to use.
copyfunc	the function to set.

stp_list_set_freefunc()

void stp_list_set_freefunc	(	stp_list_t *	list,
		stp_node_freefunc	freefunc
	)

Set a list node free function.

This callback function will be called whenever a list item is destroyed. Its intended use is for automatic object destruction and any other cleanup required.

Parameters

list	the list to use.
freefunc	the function to set.

stp_list_set_long_namefunc()

void stp_list_set_long_namefunc	(	stp_list_t *	list,
		stp_node_namefunc	long_namefunc
	)

Set a list node long name function.

This callback function will be called whenever the long name of a list item needs to be determined. This is used to find list items by long name.

Parameters

list	the list to use.
long_namefunc	the function to set.

stp_list_set_namefunc()

void stp_list_set_namefunc	(	stp_list_t *	list,
		stp_node_namefunc	namefunc
	)

Set a list node name function.

This callback function will be called whenever the name of a list item needs to be determined. This is used to find list items by name.

Parameters

list	the list to use.
namefunc	the function to set.

stp_list_set_sortfunc()

void stp_list_set_sortfunc	(	stp_list_t *	list,
		stp_node_sortfunc	sortfunc
	)

Set a list node sort function.

This callback function will be called to determine the sort order for list items in sorted lists.

Parameters

list	the list to use.
sortfunc	the function to set.