dksto(3) - Linux man page

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

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 © 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.