Next: Internal list functions
Up: Modules in deep
Previous: Printing image, blocks and
  Contents
  Index
Linked lists
Internally, GOCR abuses of linked lists to store information. They
are very useful for this kind of program, and you may need them. Include
list.h, and take advantage of our linked list functions,
which were thoroughly tested! FREE!
-
- void list_init ( List *l );
Must be called before you do any operations with the list, otherwise
strange behaviors may occur. It doesn't not allocate memory, and so
must received a non-NULL pointer.
-
- int list_app ( List *l, void *data );
Appends an element data to the end of the list. Returns 0
if OK, 1 otherwise.
-
- int list_del ( List *l, void *data );
Deletes the node containing data. Use carefully. See for_each_data,
below.
-
- int list_empty ( List *l );
Returns 1 if the list is empty, 0 otherwise.
-
- void list_free ( List *l );
Frees the list structure and nodes. Does not free the data stored
in it.
-
- void *list_get_current(l) ( List *l );
Returns the data in the current node. See for_each_data,
below.
-
- void *list_get_cur_prev(l) ( List *l );
Returns the data stored before the current node. See for_each_data,
below.
-
- void *list_get_cur_next(l) ( List *l );
Returns the data stored after the current node. See for_each_data,
below.
-
- void *list_get_header ( List *l );
Returns the data in the first node.
-
- void *list_get_tail(l) ( List *l );
Returns the data in the last node.
-
- int list_ins ( List *l, void *data_after, void *data );
Inserts data before data_after.
-
- void * list_next ( List *l, void *data );
Returns the data stored after data.
-
- void * list_prev ( List *l, void *data );
Returns the data stored before data.
-
- void list_sort(List *l, int (*compare)(const void *, const void *));
Similar to qsort: sorts the list. compare function must return
an integer less than, equal to, or greater than zero if the first
argument is considered to be respectively less than, equal to, or
greater than the second. If two members compare as equal, their order
in the sorted array is undefined. Uses a bubble sort to do the task.
-
- int list_total ( List *l );
Returns the total number of nodes in the linked list.
-
- for_each_data ( List *l ) {
-
- code
} end_for_each ( List *l );
This piece of code implements a for that sweeps the entire list, node
by node. You can get the current node data using list_get_current,
the data before it using list_get_cur_prev, and the data
after it using list_get_cur_next. Use these functions
if possible instead of list_next and list_prev,
since they are much faster.
You can nest for_each_data, but take care when you call
list_del, since you may be deleting one of the nodes that
is the current one in a lower level. The internal code takes care
of access to previous/next elements of the now defunct node. Here's
an example:
-
- for_each_data(l) {
-
- for_each_data(l) {
-
- list_del(l, header_data);
free(header_data);
} end_for_each(l);
tempnode = list_cur_next(l);
} end_for_each(l);
Although you have deleted the current node of the outer loop, the
line in italic will work as if nothing happened. But if it's replaced
with:
-
- tempnode = list_next(l, list_get_current(l));
the code will break, since list_get_current will return
either NULL or some garbage. The best way to avoid this problem is
not using list_del in a big stack of loops, or test the
return value of list_get_current(). You can use break
and continue, just as if you were in a normal for loop, but
never use a goto to somewhere outside the loop (theoretically
you can do it, using the list_lower function explained below,
but if you do take care).
Note: if you have two elements with the same data, the functions will
assume that the first one is the wanted one. Not a bug, a feature.
Another note: avoid calling list_prev and list_next.
They are intensive and slow functions. Keep the result in a variable
or, if you need something more, use list_get_element_from_data,
described below.
Subsections
Next: Internal list functions
Up: Modules in deep
Previous: Printing image, blocks and
  Contents
  Index
root
2002-02-17