dksto.h File Reference

Unsorted and sorted containers. More...

#include <dk.h>
#include <dktypes.h>

Go to the source code of this file.

Defines

#define DK_STO_SIZE_HUGE   0
 Container size (number of elements): Maximum - Recommended.
#define DK_STO_SIZE_LARGE   1
 Container size (number of elements): Large, < 1.17987*10^214.
#define DK_STO_SIZE_MEDIUM   2
 Container size (number of elements): Medium, < 1.17534*10^107.
#define DK_STO_SIZE_SMALL   3
 Container size (number of elements): Small, < 6.59035*10^26.
#define DK_STO_SIZE_TINY   4
 Container size (number of elements): Smallest, < 2.77779*10^13.

Functions

dk_storage_tdksto_open (int c)
 Create a new containter (dk_storage_t).
int dksto_set_eval_c (dk_storage_t *c, dk_fct_eval_c_t *f, int s)
 Set char type evaluation function and criteria for container.
int dksto_set_eval_uc (dk_storage_t *c, dk_fct_eval_uc_t *f, int s)
 Set unsigned char type evaluation function and criteria for container.
int dksto_set_eval_s (dk_storage_t *c, dk_fct_eval_s_t *f, int s)
 Set short type evaluation function and criteria for container.
int dksto_set_eval_us (dk_storage_t *c, dk_fct_eval_us_t *f, int s)
 Set unsigned short type evaluation function and criteria for container.
int dksto_set_eval_i (dk_storage_t *c, dk_fct_eval_i_t *f, int s)
 Set int type evaluation function and criteria for container.
int dksto_set_eval_ui (dk_storage_t *c, dk_fct_eval_ui_t *f, int s)
 Set unsigned int type evaluation function and criteria for container.
int dksto_set_eval_l (dk_storage_t *c, dk_fct_eval_l_t *f, int s)
 Set long type evaluation function and criteria for container.
int dksto_set_eval_ul (dk_storage_t *c, dk_fct_eval_ul_t *f, int s)
 Set unsigned long type evaluation function and criteria for container.
int dksto_set_eval_f (dk_storage_t *c, dk_fct_eval_f_t *f, int s)
 Set float type evaluation function and criteria for container.
int dksto_set_eval_d (dk_storage_t *c, dk_fct_eval_d_t *f, int s)
 Set double type evaluation function and criteria for container.
int dksto_set_comp (dk_storage_t *c, dk_fct_comp_t *f, int s)
 Set object comparison function and search criteria for container.
void dksto_close (dk_storage_t *c)
 Close a containter obtained from dksto_open().
void dksto_remove_all (dk_storage_t *c)
 Remove all object pointers from container.
int dksto_remove (dk_storage_t *c, void *o)
 Remove one object pointer from the container.
int dksto_add (dk_storage_t *c, void *o)
 Add object pointer to container.
dk_storage_iterator_tdksto_it_open (dk_storage_t *c)
 Create iterator for container.
void dksto_it_close (dk_storage_iterator_t *i)
 Close iterator and release memory for an iterator obtained from dksto_it_open().
void dksto_it_reset (dk_storage_iterator_t *i)
 Reset iterator.
void * dksto_it_next (dk_storage_iterator_t *i)
 Retrieve next pointer for iterator.
void * dksto_it_find_exact (dk_storage_iterator_t *i, void *o)
 Find the object o.
void * dksto_it_find_like (dk_storage_iterator_t *i, void *o, int s)
 Find the first object evaluated equally to o.
int dksto_use_trees (dk_storage_t *c, int f)
 Allow/deny the use of AVL-trees for sorted storages (obsoleted).
void * dksto_find_root (dk_storage_t *c)
 Find object placed at the root of the containers tree.
void * dksto_it_find_parent (dk_storage_iterator_t *i)
 Find object placed as parent of the iterators current object in the containers tree.
void * dksto_it_find_left (dk_storage_iterator_t *i)
 Find object placed as left child of the iterators current object in the containers tree.
void * dksto_it_find_right (dk_storage_iterator_t *i)
 Find object placed as right child of the iterators current object in the containers tree.
void * dksto_it_find_root (dk_storage_iterator_t *i)
 Find object placed at the root of the iterators container.


Detailed Description

Unsorted and sorted containers.

This module contains functions to store pointers in sorted and unsorted containers, to search for objects in containers and to iterate through containers.

To create containers for sorted storage set a comparison or evaluation function for a container immediately after creating the container and before inserting the first element.

The file stotest.c contains an example for sorted storage. See stotest - Test program for storage containers for details.


Function Documentation

int dksto_add ( dk_storage_t c,
void *  o 
)

Add object pointer to container.

Parameters:
c Pointer to the container.
o Object pointer to add.
Returns:
Flag to indicate success.
Examples:
stotest.c.

void dksto_close ( dk_storage_t c  ) 

Close a containter obtained from dksto_open().

Parameters:
c Pointer to the container.
Examples:
stotest.c.

void* dksto_find_root ( dk_storage_t c  ) 

Find object placed at the root of the containers tree.

Parameters:
c Pointer to the container.
Returns:
Object pointer placed at the containers trees root or NULL if there are no elements in the container.

void dksto_it_close ( dk_storage_iterator_t i  ) 

Close iterator and release memory for an iterator obtained from dksto_it_open().

Parameters:
i Pointer to the iterator to close.
Examples:
stotest.c.

void* dksto_it_find_exact ( dk_storage_iterator_t i,
void *  o 
)

Find the object o.

The iterator is set to object o, the following calls to dksto_it_next() will deliver the objects after o.

Parameters:
i Pointer to the iterator.
o Object pointer.
Returns:
Pointer to o or NULL if the object was not found.

void* dksto_it_find_left ( dk_storage_iterator_t i  ) 

Find object placed as left child of the iterators current object in the containers tree.

Parameters:
i Pointer to iterator.
Returns:
Object pointer or NULL.

void* dksto_it_find_like ( dk_storage_iterator_t i,
void *  o,
int  s 
)

Find the first object evaluated equally to o.

The function searches for the first object which is evaluated equally to o using the evaluation/comparison functions set for the container. The folling calls to dksto_it_next() will deliver the objects after the object found.

Parameters:
i Pointer to the iterator.
o Object pointer.
s Search/comparison/evaluation criteria.
Returns:
Pointer to first object evaluated equally to o or NULL if no such object is found.
Examples:
stotest.c.

void* dksto_it_find_parent ( dk_storage_iterator_t i  ) 

Find object placed as parent of the iterators current object in the containers tree.

Parameters:
i Pointer to iterator.
Returns:
Object pointer or NULL.

void* dksto_it_find_right ( dk_storage_iterator_t i  ) 

Find object placed as right child of the iterators current object in the containers tree.

Parameters:
i Pointer to iterator.
Returns:
Object pointer or NULL.

void* dksto_it_find_root ( dk_storage_iterator_t i  ) 

Find object placed at the root of the iterators container.

Parameters:
i Pointer to the iterator.
Returns:
Pointer to object placed at the root of the iterators containers tree or NULL.

void* dksto_it_next ( dk_storage_iterator_t i  ) 

Retrieve next pointer for iterator.

Parameters:
i Pointer to the iterator.
Examples:
stotest.c.

dk_storage_iterator_t* dksto_it_open ( dk_storage_t c  ) 

Create iterator for container.

The iterator is created in dynamically allocated memory. You must destroy it/release the memory using dksto_it_close() if the iterator is not longer needed and before calling dksto_close() on the container.

Parameters:
c Pointer to the container.
Returns:
Pointer to the new iterator on success, nULL on error.
Examples:
stotest.c.

void dksto_it_reset ( dk_storage_iterator_t i  ) 

Reset iterator.

The next call of dksto_it_next() will return pointer to the first object (if any).

Parameters:
i Pointer to the iterator.
Examples:
stotest.c.

dk_storage_t* dksto_open ( int  c  ) 

Create a new containter (dk_storage_t).

For sorted containers we need to store a critical path during insert and remove operations. The c parameter controls the size of the critical path (64, 128, 512, 1024 or 1536) which affects the number of elements which can be stored in the container. The container is created in dynamically allocated memory, you must release the memory by calling dksto_close() when the container is no longer used. To switch the container to sorted storage call one of the dksto_set_eval_...() or dksto_set_comp() functions before inserting the first element.

Parameters:
c Key number to specify the critical path length. The recommended value is DK_STO_SIZE_HUGE.
Returns:
Pointer to the new container on success, NULL on error.
Examples:
stotest.c.

int dksto_remove ( dk_storage_t c,
void *  o 
)

Remove one object pointer from the container.

Parameters:
c Pointer to the container.
o Object pointer to remove.
Returns:
Flag to indicate success.
Examples:
stotest.c.

void dksto_remove_all ( dk_storage_t c  ) 

Remove all object pointers from container.

Parameters:
c Pointer to the container.

int dksto_set_comp ( dk_storage_t c,
dk_fct_comp_t f,
int  s 
)

Set object comparison function and search criteria for container.

Parameters:
c Pointer to container.
f Pointer to comparison funtion.
s Criteria passed to comparison function.
Returns:
Flag to indicate success.
Examples:
stotest.c.

int dksto_set_eval_c ( dk_storage_t c,
dk_fct_eval_c_t f,
int  s 
)

Set char type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_d ( dk_storage_t c,
dk_fct_eval_d_t f,
int  s 
)

Set double type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_f ( dk_storage_t c,
dk_fct_eval_f_t f,
int  s 
)

Set float type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_i ( dk_storage_t c,
dk_fct_eval_i_t f,
int  s 
)

Set int type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_l ( dk_storage_t c,
dk_fct_eval_l_t f,
int  s 
)

Set long type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_s ( dk_storage_t c,
dk_fct_eval_s_t f,
int  s 
)

Set short type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_uc ( dk_storage_t c,
dk_fct_eval_uc_t f,
int  s 
)

Set unsigned char type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_ui ( dk_storage_t c,
dk_fct_eval_ui_t f,
int  s 
)

Set unsigned int type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_set_eval_ul ( dk_storage_t c,
dk_fct_eval_ul_t f,
int  s 
)

Set unsigned long type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.
Examples:
stotest.c.

int dksto_set_eval_us ( dk_storage_t c,
dk_fct_eval_us_t f,
int  s 
)

Set unsigned short type evaluation function and criteria for container.

Parameters:
c Pointer to container.
f Pointer to evaluation function.
s Criteria passed to evaluation function.
Returns:
Flag to indicate success.

int dksto_use_trees ( dk_storage_t c,
int  f 
)

Allow/deny the use of AVL-trees for sorted storages (obsoleted).

By default this feature is turned on. This function can only be used if there is no pointer stored in the container.

Parameters:
c Pointer to container.
f Flag to allow the use of AVL-trees.
Returns:
Flag to indicate success.


Generated on Thu Feb 25 13:48:24 2010 for dklibs by  doxygen 1.5.8