/**	@file	dk3sto.h	Unsorted and sorted data storage.

The dk3sto.c module stores data (to be exact: it stores pointers to data).

A storage of the dk3_sto_t type can also be referred to as container.
Data can be stored sorted or unsorted. Double linked lists are used
for unsorted storage, AVL trees are used for sorted storage.

Sorting can be based on either evaluation of data or on comparisons.
In the programs and libraries from the dktools project you will find
storage sorted by comparison.

Evaluation means we pass a pointer to data to a function and the function
returns one result for the data the pointer is for, i.e. the age of a
person, the size of a tower...

For comparison two pointers and a comparison criteria are passed to the
comparison function and the function decides which of the pointers must
appear sooner and which of the pointers must appear later in the storage.
In simple cases - especially if all objects are of equal type - the function
can ignore the comparison criteria.

If you want to store data in a "struct person ..." data type you may want
to compare two structs by person name
in insert/remove operations in the storage and you
want to compare a struct person against a given name when searching for
the struct person for a name.
In such cases you can use the comparison criteria to indicate the types
of pointers passed to the comparison function.

Iterators can be used to access data stored in a storage.
For unsorted storages you can reset an iterator using
dk3sto_it_reset() and call dk3sto_it_next() to get the next pointer
until it returns NULL.

For sorted storages you additionaly can use dk3sto_it_find_exact() or
dk3sto_it_find_like() to find one pointer or the first pointer
evaluating/comparing equally to a pointer. On success these functions return
a result and set the iterator to the element found. Subsequent calls
to dk3sto_it_next() will return the pointers after the element found.

The example file ex-sto.c provides an example for sorted storage and
search.
*/