list

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

Typedefs
typedef stp_list_item	stp_list_item_t
	The list item opaque data type.
typedef stp_list	stp_list_t
	The list opaque data type.
typedef void(*	stp_node_freefunc )(void *)
	A callback function to free the data a node contains.
typedef void *(*	stp_node_copyfunc )(const void *)
	A callback function to copy the data a node contains.
typedef const char *(*	stp_node_namefunc )(const void *)
	A callback function to get the name of a node.
typedef int(*	stp_node_sortfunc )(const void *, const void *)
	A callback function to compare two nodes.
Functions
void	stp_list_node_free_data (void *item)
	Free node data allocated with stp_malloc.
stp_list_t *	stp_list_create (void)
	Create a new list object.
stp_list_t *	stp_list_copy (const stp_list_t *list)
	Copy and allocate a list object.
int	stp_list_destroy (stp_list_t *list)
	Destroy a list object.
stp_list_item_t *	stp_list_get_start (const stp_list_t *list)
	Find the first item in a list.
stp_list_item_t *	stp_list_get_end (const stp_list_t *list)
	Find the last item in a list.
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.
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.
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.
int	stp_list_get_length (const stp_list_t *list)
	Get the length of a list.
void	stp_list_set_freefunc (stp_list_t *list, stp_node_freefunc freefunc)
	Set a list node free function.
stp_node_freefunc	stp_list_get_freefunc (const stp_list_t *list)
	Get a list node free function.
void	stp_list_set_copyfunc (stp_list_t *list, stp_node_copyfunc copyfunc)
	Set a list node copy function.
stp_node_copyfunc	stp_list_get_copyfunc (const stp_list_t *list)
	Get a list node copy function.
void	stp_list_set_namefunc (stp_list_t *list, stp_node_namefunc namefunc)
	Set a list node name function.
stp_node_namefunc	stp_list_get_namefunc (const stp_list_t *list)
	Get a list node name function.
void	stp_list_set_long_namefunc (stp_list_t *list, stp_node_namefunc long_namefunc)
	Set a list node long name function.
stp_node_namefunc	stp_list_get_long_namefunc (const stp_list_t *list)
	Get a list node long name function.
void	stp_list_set_sortfunc (stp_list_t *list, stp_node_sortfunc sortfunc)
	Set a list node sort function.
stp_node_sortfunc	stp_list_get_sortfunc (const stp_list_t *list)
	Get a list node sort function.
int	stp_list_item_create (stp_list_t *list, stp_list_item_t *next, const void *data)
	Create a new list item.
int	stp_list_item_destroy (stp_list_t *list, stp_list_item_t *item)
	Destroy a list item.
stp_list_item_t *	stp_list_item_prev (const stp_list_item_t *item)
	Get the previous item in the list.
stp_list_item_t *	stp_list_item_next (const stp_list_item_t *item)
	Get the next item in the list.
void *	stp_list_item_get_data (const stp_list_item_t *item)
	Get the data associated with a list item.
int	stp_list_item_set_data (stp_list_item_t *item, void *data)
	Set the data associated with a list item.

---

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

typedef struct stp_list_item stp_list_item_t

The list item opaque data type. This object is a node in the list.

typedef struct stp_list stp_list_t

The list opaque data type. This object represents the list as a whole.

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.

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.

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.

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_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_t* stp_list_create (  void   )

Create a new list object. Returns: the newly created list object.

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_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_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_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_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_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_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.

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_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_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_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_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.

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).

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.

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_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_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.

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).

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

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.

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.

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.

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.

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.

---