dklibs(3)

NAME
dksto - data storage module

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);

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 dk_fct_eval_...() function types are used to evaluate a data object. An additional criteria cr is used to evaluate the data object.

The dk_fct_comp_...() function type is used to compare two data objects. The cr parameter is a criteria how to compare them. Like strcmp() these functions return -1 to indicate the left side object is "smaller" than the right side object, 1 if the left side object is "larger", 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 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 sz is 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 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 (ok=0) or enable (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 o argument matching the cr criteria.

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

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

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

AUTHOR
Dirk Krause

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.