=head1	NAME

dksto - data storage module

=head1	SYNOPSIS

  #include <dktypes.h>
  #include <dksto.h>

  typedef char dk_fct_eval_c_t(void *obj, int crit);
  typedef unsigned char dk_fct_eval_uc_t(void *obj, int crit);
  typedef short dk_fct_eval_s_t(void *obj, int crit);
  typedef unsigned short dk_fct_eval_us_t(void *obj, int crit);
  typedef int dk_fct_eval_i_t(void *obj, int crit);
  typedef unsigned int dk_fct_eval_ui_t(void *obj, int crit);
  typedef long dk_fct_eval_l_t(void *obj, int crit);
  typedef unsigned long dk_fct_eval_ul_t(void *obj, int crit);
  typedef float dk_fct_eval_f_t(void *obj, int crit);
  typedef double dk_fct_eval_d_t(void *obj, int crit);
  typedef int dk_fct_comp_t(void *o1, void *o2, int crit);
  
  dk_storage_t *
  dksto_open (int sz);
  
  void
  dksto_close (dk_storage_t *sz);
  
  int
  dksto_set_eval_c (dk_storage_t *st, dk_fct_eval_c_t *f, int cr);
  
  int
  dksto_set_eval_uc (dk_storage_t *st, dk_fct_eval_uc_t *f, int cr);
  
  int
  dksto_set_eval_s (dk_storage_t *st, dk_fct_eval_s_t *f, int cr);
  
  int
  dksto_set_eval_us (dk_storage_t *st, dk_fct_eval_us_t *f, int cr);
  
  int
  dksto_set_eval_i (dk_storage_t *st, dk_fct_eval_i_t *f, int cr);
  
  int
  dksto_set_eval_ui (dk_storage_t *st, dk_fct_eval_ui_t *f, int cr);
  
  int
  dksto_set_eval_l (dk_storage_t *st, dk_fct_eval_l_t *f, int cr);
  
  int
  dksto_set_eval_ul (dk_storage_t *st, dk_fct_eval_ul_t *f, int cr);
  
  int
  dksto_set_eval_f (dk_storage_t *st, dk_fct_eval_f_t *f, int cr);
  
  int
  dksto_set_eval_d (dk_storage_t *st, dk_fct_eval_d_t *f, int cr);
  
  int
  dksto_set_comp (dk_storage_t *st, dk_fct_comp_t *f, int cr);
  
  int
  dksto_use_trees (dk_storage_t *st, int ok);
  
  int
  dksto_remove (dk_storage_t *st, void *o);
  
  int
  dksto_add (dk_storage_t *st, void *o);
  
  dk_storage_iterator_t *
  dksto_it_open (dk_storage_t *st);
  
  void
  dksto_it_close (dk_storage_iterator_t *it);
  
  void
  dksto_it_reset (dk_storage_iterator_t *it);
  
  void *
  dksto_it_next (dk_storage_iterator_t *it);
  
  void *
  dksto_it_find_exact (dk_storage_iterator_t *it, void *o);
  
  void *
  dksto_it_find_like (dk_storage_iterator_t *it, void *o, int cr);

=head1	DESCRIPTION

This module allow to store data in a data storage (container). Unsorted
containers are internally implemented as linked lists, sorted containers
use AVL-trees.

Iterators can be used to traverse the containers.

The I<dk_fct_eval_...()> function types are
used to evaluate a data object. An additional criteria I<cr> is used
to evaluate the data object.

The I<dk_fct_comp_...()> function type is used to compare two data
objects. The I<cr> parameter is a criteria how to compare them.
Like strcmp() these functions return I<-1> to indicate the left side
object is "smaller" than the right side object, I<1> if the left
side object is "larger", I<0> if the objects are equal.

The dksto_open() function creates a new container and returns a valid
pointer on success, NULL on error. The I<sz> parameter specifies the
length of the internal backtracking path, it can be one of:

                                       possible number of
  sz parameter         path length   objects in containter
  ----------------     -----------   ---------------------
  DK_STO_SIZE_HUGE        1536       exceeds 1.3*10^308
  DK_STO_SIZE_LARGE       1024         1.179*10^214
  DK_STO_SIZE_MEDIUM       512         1.175*10^107
  DK_STO_SIZE_SMALL        128         6.590*10^26
  DK_STO_SIZE_TINY          64         2.777*10^13

The suggsted value for I<sz> is I<DK_STO_SIZE_HUGE> except for programs
running on systems with low amount of memory (i.e. DOS).

After usage the container must
be destroyed using the dksto_close() function.

If you want to use a container for sorted storage you need to
run one of the I<dksto_set_eval_...()> functions or the
dksto_set_comp() function. All data objects inserted into the container
are evaluated or compared using the specified evaluation or comparison
function and criteria.

The dksto_use_trees() function can be used to disable (I<ok>=0) or
enable (I<ok>=1) the use of AVL-trees in sorted containers. This function
should not be used.

The dksto_add() function adds an object to the container. The container
only stores a pointer to the object, it does not create a copy.

The dksto_remove() function removes an object from the container.

The dksto_it_open() function creates a new iterator for the container.
An iterator can be used to either search for a specific object or to
traverse the container.

After usage an iterator must be destroyed using the dksto_it_close()
function before the container is closed by dksto_close().

The dksto_it_reset() function resets an iterator, the next call
to dksto_it_next() will return a pointer to the first object in
the container.

The dksto_it_find_exact() function searches for the specified object
in the container and sets the iterator to point to this object.

The dksto_it_find_like() function searches for the first object having
the same evaluation as the I<o> argument matching the I<cr> criteria.

The dksto_it_next() function increments to iterator (goes to the next
object) and returns a pointer to the object.

=head1	RETURN VALUE

All functions returning pointers return a valid pointer on success,
NULL on errors.

Functions returning I<int> values (except the evaluation and comparison
functions) return 0 to indicate an error, positive values to indicate
success.

=head1	AUTHOR

Dirk Krause

=head1	COPYRIGHT AND LICENSE

Copyright (c) 2001-2008, Dirk Krause
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

 * Redistributions of source code must retain the above
   copyright notice, this list of conditions and the
   following disclaimer.

 * Redistributions in binary form must reproduce the above
   copyright notice, this list of conditions and the following
   disclaimer in the documentation and/or other materials
   provided with the distribution.

 * Neither the name of the Dirk Krause nor the names of
   contributors may be used to endorse or promote products
   derived from this software without specific prior written
   permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
