[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4.2 List functions

A simple doubly-linked list implementation is included in libgimpprint. A doubly-linked list differs from the static arrays of structures that have been used previously in that entries in the lists may be added and removed at will. "Items" are often referred to as "nodes" elsewhere, but one generally has items in a list in real life, not nodes.

Each item in the list contains pointers to the previous and next items in the list. This means that you can easily access all the items in the list in a forward or backward direction.

Callbacks (functions) may be registered with each list to control list sorting, freeing of item data, and searching for individual items by their name or long name (if any). These are all optional, but can make things much simpler when used correctly.

Data type: void stp_list_t
This is an opaque data type, whose structure is not visible to the user. This object is the "head" of a doubly-linked list, i.e. it contains the list, but is not the list itself. It contains information about the size of the list, and function pointers to various callbacks that may be registered. It also contains pointers to the start and end of the list.

Data type: void stp_list_item_t
This is an opaque data type, whose structure is not visible to the user. This object contains the information about an individual item in the list: the data (which you define), and pointers to the next and previous items in the list. The list is a collection of stp_list_item_t structures.

The stp_list_t and stp_list_item_t data types are never used directly. They are accessed by a collection of accessor functions, described below.

Function: stp_list_t * stp_list_create (void)
Allocate a new list. A new list is created and returned. The list is completely empty and no callbacks are registered.

Function: int stp_list_destroy (stp_list_t *list)
Destroy the list. All memory allocated by list is freed. list may not be used again without calling stp_list_create.

Function: stp_list_item_t * stp_list_get_start (stp_list_t *list)
Get the first item in the list. The first item in list is returned. If the list is empty, the return value will be NULL.

Function: stp_list_item_t * stp_list_get_end (stp_list_t *list)
Get the last item in the list. The last item in list is returned. If the list is empty, the return value will be NULL.

Function: stp_list_item_t * stp_list_get_item_by_index (stp_list_t *list, int index)
Get the item at a particular location in the list. The item at position index in list is returned. If the list is empty, or index is not a valid position in the list, the return value will be NULL.

Function: stp_list_item_t * stp_list_get_item_by_name (stp_list_t *list, const char *name)
Get the item with a particular name in the list. The item named with name in list is returned. If the list is empty, or name is not a valid name in the list, the return value will be NULL. If the name is repeated in the list, the first occurrence of name will be returned.

This function requires a callback registering with stp_list_set_namefunc. If no function is registered, the return value will be NULL.

Function: stp_list_item_t * stp_list_get_item_by_long_name (stp_list_t *list, const char *long_name)
Get the item with a particular long name in the list. The item named with long_name in list is returned. If the list is empty, or long_name is not a valid name in the list, the return value will be NULL. If the long name is repeated in the list, the first occurrence of long_name will be returned.

This function requires a callback registering with stp_list_set_long_namefunc. If no function is registered, the return value will be NULL.

Function: int stp_list_get_length (stp_list_t *list)
Get the total number of items in the list.

The list functions know nothing about the data associated with each item in this list. Therefore callbacks may be registered to add any special functionality required.

Function: void stp_list_set_freefunc (stp_list_t *list, void (*node_freefunc)(stp_list_item_t *item))
Register a callback for freeing item data. By default, the data associated with each item is not freed. However, when you remove a node, it can be useful to automatically free the memory used by the data associated with that node. By registering your own callback (node_freefunc), when a node is removed from list, your function will be called to free the data.

Function: void stp_list_set_namefunc (stp_list_t *list, const char *(*namefunc)(const stp_list_item_t *item))
Register a callback for getting an item name. If the data you are storing in each item has a name associated with it, then by registering this callback (namefunc) with list you can then easily retrieve items from the list with stp_list_get_item_by_name.

Function: void stp_list_set_long_namefunc (stp_list_t *list, const char *(*long_namefunc)(const stp_list_item_t *item))
Register a callback for getting an item long name. If the data you are storing in each item has a long name associated with it, then by registering this callback (long_namefunc) with list you can then easily retrieve items from the list with stp_list_get_item_by_long_name.

Function: void stp_list_set_sortfunc (stp_list_t *list, int (*sortfunc)(const stp_list_item_t *item1, const stp_list_item_t *item2))
Register a callback for sorting items in the list. When items are added to the list, rather than selecting a point in list to insert the item, the items may be sorted by the callback sortfunc. The function takes two stp_list_item_t objects as arguments; the first is the item in the list, while the second is the item to insert. Comparion takes place from the start to the end of the list, taking each item in turn. sortfunc should return an int > 1 when insertion is valid, otherwise an value < 1.

Function: int stp_list_item_create (stp_list_t *list, stp_list_item_t *prev, void *data)
Create a new list item. A new item is inserted into list, with the data from data associated with it. data must be cast to void *, but any data type may be contained in the list. If prev is specified, the new node will be inserted after this node. If prev is NULL, the new item will be inserted at the start of the list. However, if prev is NULL and a sorting callback has been registered with stp_list_set_sortfunc, the item will be inserted according to its sorted position in the list.

Function: int stp_list_item_destroy (stp_list_t *list, stp_list_item_t *item)
Remove an item from the list. item is removed from list, and if a free callback has been registered with stp_list_set_freefunc, the data associated with the item will also be freed.

Function: stp_list_item_t * stp_list_item_prev (stp_list_item_t *item)
Get the item in the list following item. The next item in the list will be returned. If item is the last node in the list, then NULL is returned.

Function: stp_list_item_t * stp_list_item_next (stp_list_item_t *item)
Get the item in the list before item. The previous item in the list will be returned. If item is the first node in the list, then NULL is returned.

Function: void * stp_list_item_get_data (const stp_list_item_t *item)
Get the data associated with a list item. The data set when the node was created with stp_list_item_create or with stp_list_item_set_data is returned.

Function: int stp_list_item_set_data (stp_list_item_t *item, void *data)
Set the data associated with a list item. item is associated with data. As with stp_list_node_create, data may be any data type cast to void *.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Robert Krawitz on December, 24 2003 using texi2html