libgutenprint API Reference  5.2.9
Typedefs | Functions
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.
typedef struct 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_tstp_list_create (void)
 Create a new list object.
stp_list_tstp_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_tstp_list_get_start (const stp_list_t *list)
 Find the first item in a list.
stp_list_item_tstp_list_get_end (const stp_list_t *list)
 Find the last item in a list.
stp_list_item_tstp_list_get_item_by_index (const stp_list_t *list, int idx)
 Find an item in a list by its index.
stp_list_item_tstp_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_tstp_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_tstp_list_item_prev (const stp_list_item_t *item)
 Get the previous item in the list.
stp_list_item_tstp_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:
listthe 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:
listthe 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:
listthe 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:
listthe 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:
listthe 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:
listthe list to use.
idxthe 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:
listthe list to use.
long_namethe 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:
listthe list to use.
namethe 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:
listthe 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:
listthe 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:
listthe 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:
listthe 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:
listthe 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:
listthe list to use.
nextthe next item in the list, or NULL to insert at the end of the list.
datathe 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:
listthe list to use.
itemthe 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:
itemthe 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:
itemthe 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:
itemthe 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:
itemthe list item to use.
datathe 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:
itemthe 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:
listthe list to use.
copyfuncthe 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:
listthe list to use.
freefuncthe 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:
listthe list to use.
long_namefuncthe 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:
listthe list to use.
namefuncthe 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:
listthe list to use.
sortfuncthe function to set.