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 *
.
This document was generated
by Robert Krawitz on December, 8 2002
using texi2html