Main Page | Class List | File List | Class Members | File Members | Related Pages

dataset.h File Reference

Arbitrary key/data association data structure. More...

#include "list.h"
#include "array.h"

Go to the source code of this file.

Classes

struct  ds_data_t
struct  dataset_node

Defines

#define DS_NOCOPY   0x01
#define DATASET_DEFAULT   DATASET_HASH
#define DS_NOTFOUND   0x00 /**< DS_FIND: Continue iteration */
#define DS_FOUND   0x02 /**< DS_FIND: Found, halt iteration */
#define DS_CONTINUE   0x01 /**< DS_FOREACH: Continue iteration */
#define DS_BREAK   0x02 /**< DS_FOREACH: Halt iteration */
#define DS_REMOVE   0x04 /**< DS_FOREACH: Remove the node */
#define DS_FOREACH(func)   ((DatasetForeachFn)func)
#define DS_FOREACH_EX(func)   ((DatasetForeachExFn)func)
#define DS_FIND(func)   ((DatasetFindFn)func)

Typedefs

typedef dataset Dataset
typedef dataset_node DatasetNode
typedef void(* DatasetForeachFn )(ds_data_t *key, ds_data_t *value, void *udata)
typedef int(* DatasetForeachExFn )(ds_data_t *key, ds_data_t *value, void *udata)
typedef DatasetForeachExFn DatasetFindFn

Enumerations

enum  DatasetType { DATASET_LIST, DATASET_ARRAY, DATASET_HASH }

Functions

EXTERN_C_BEGIN LIBGIFT_EXPORT
Dataset * 		dataset_new (DatasetType type)
LIBGIFT_EXPORT void dataset_clear (Dataset *d)
LIBGIFT_EXPORT void ds_data_init (ds_data_t *dsdata, const void *data, size_t len, int flags)
LIBGIFT_EXPORT DatasetNode * dataset_insert_ex (Dataset **d, ds_data_t *key, ds_data_t *value)
LIBGIFT_EXPORT DatasetNode * dataset_insert (Dataset **d, const void *key, size_t key_len, const void *value, size_t value_len)
LIBGIFT_EXPORT DatasetNode * dataset_insertstr (Dataset **d, const char *key, const char *value)
LIBGIFT_EXPORT void dataset_remove_ex (Dataset *d, ds_data_t *key)
LIBGIFT_EXPORT void dataset_remove (Dataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void dataset_removestr (Dataset *d, const char *key)
LIBGIFT_EXPORT void dataset_remove_node (Dataset *d, DatasetNode *node)
LIBGIFT_EXPORT ds_data_t * dataset_lookup_ex (Dataset *d, ds_data_t *key)
LIBGIFT_EXPORT void * dataset_lookup (Dataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void * dataset_lookupstr (Dataset *d, const char *key)
LIBGIFT_EXPORT DatasetNode * dataset_lookup_node_ex (Dataset *d, ds_data_t *key)
LIBGIFT_EXPORT DatasetNode * dataset_lookup_node (Dataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void dataset_foreach (Dataset *d, DatasetForeachFn func, void *udata)
LIBGIFT_EXPORT void dataset_foreach_ex (Dataset *d, DatasetForeachExFn func, void *udata)
LIBGIFT_EXPORT void * dataset_find (Dataset *d, DatasetFindFn func, void *udata)
LIBGIFT_EXPORT DatasetNode * dataset_find_node (Dataset *d, DatasetFindFn func, void *udata)
LIBGIFT_EXPORT unsigned int dataset_length (Dataset *d)
LIBGIFT_EXPORT List * dataset_flatten (Dataset *d)
LIBGIFT_EXPORT uint32_t dataset_uniq32 (Dataset *d, uint32_t *counter)

Detailed Description

Arbitrary key/data association data structure.

Flexible data structure used for management of arbitrary sets of data. Currently supports a hash table and a linked list backend, btree should come soon.

Define Documentation

#define DS_BREAK   0x02 /**< DS_FOREACH: Halt iteration */
 

DS_FOREACH: Halt iteration

#define DS_CONTINUE   0x01 /**< DS_FOREACH: Continue iteration */
 

DS_FOREACH: Continue iteration

#define DS_FOREACH (  func   )     ((DatasetForeachFn)func)
 

Helper macro for properly typecasting iterator functions.

#define DS_FOUND   0x02 /**< DS_FIND: Found, halt iteration */
 

DS_FIND: Found, halt iteration

#define DS_NOTFOUND   0x00 /**< DS_FIND: Continue iteration */
 

DS_FIND: Continue iteration

#define DS_REMOVE   0x04 /**< DS_FOREACH: Remove the node */
 

DS_FOREACH: Remove the node

Typedef Documentation

typedef int(* DatasetForeachExFn)(ds_data_t *key, ds_data_t *value, void *udata)
 

Extended dataset iterator capable of basic flow control and removal of entries as you pass by them.

Returns:
One of either DS_CONTINUE or DS_BREAK, optionally OR'd against DS_REMOVE.

typedef void(* DatasetForeachFn)(ds_data_t *key, ds_data_t *value, void *udata)
 

Main dataset iterator callback. See DatasetForeachExFn for the extended type.

Enumeration Type Documentation

enum DatasetType
 

Selects the backend data structure implementation for the dataset to use.

Enumeration values:
DATASET_LIST  Linked list
DATASET_ARRAY  Dynamically allocated array
DATASET_HASH  Hash table

Function Documentation

LIBGIFT_EXPORT void dataset_clear (  Dataset *  d  ) 
 

Unallocate a dataset and all internally allocated variables.

LIBGIFT_EXPORT void* dataset_find (  Dataset *  d,
DatasetFindFn  func,
void *  udata
) 
 

Locate a set value through iteration. See dataset_find_node.

Returns:
Pointer to the value entry found.

LIBGIFT_EXPORT DatasetNode* dataset_find_node (  Dataset *  d,
DatasetFindFn  func,
void *  udata
) 
 

Locate a dataset node through iteration. DatasetForeach returns TRUE when the set has been found.

LIBGIFT_EXPORT List* dataset_flatten (  Dataset *  d  ) 
 

Flatten a dataset to a reallocated list. The values are not copied.

LIBGIFT_EXPORT void dataset_foreach (  Dataset *  d,
DatasetForeachFn  func,
void *  udata
) 
 

Iterate an entire dataset. This is the simplest form and does not have any kind of flow control of extended features.

Note:
This iterator is optimized under the assumption that the dataset integrity will not be affected during iteration. If you can not guarantee this, you must use dataset_foreach_ex.

LIBGIFT_EXPORT void dataset_foreach_ex (  Dataset *  d,
DatasetForeachExFn  func,
void *  udata
) 
 

Extended iterator for the dataset capable of simple flow control and removal of entries as you pass over them. See dataset_foreach for more details.

LIBGIFT_EXPORT DatasetNode* dataset_insert (  Dataset **  d,
const void *  key,
size_t  key_len,
const void *  value,
size_t  value_len
) 
 

Insert a new key/value set. If the value at d is NULL, a new dataset will be allocated using DATASET_DEFAULT.

Parameters:
d 
key Storage location of the lookup key.
key_len Length of key for copying.
value Storage location of the value.
value_len Length of value if you wish for the dataset to internally manage the values memory, otherwise 0 in which case dataset_clear will not free this address.
Returns:
Node handle that has just been inserted, or NULL on error.

LIBGIFT_EXPORT DatasetNode* dataset_insert_ex (  Dataset **  d,
ds_data_t *  key,
ds_data_t *  value
) 
 

Base implementation for dataset_insert and dataset_insertstr.

LIBGIFT_EXPORT DatasetNode* dataset_insertstr (  Dataset **  d,
const char *  key,
const char *  value
) 
 

Wrapper around dataset_insert for string constants. Copies both key and value.

LIBGIFT_EXPORT unsigned int dataset_length (  Dataset *  d  ) 
 

Calculate the dataset length (total number of sets currently inserted). Please note that the DATASET_LIST backend requires iteration to perform this task and as such is considered expensive.

Return values:
Number of data entries in the set.

LIBGIFT_EXPORT void* dataset_lookup (  Dataset *  d,
const void *  key,
size_t  key_len
) 
 

Lookup a value by the set's key. If you need to know the value_len, consider using dataset_lookup_node.

LIBGIFT_EXPORT ds_data_t* dataset_lookup_ex (  Dataset *  d,
ds_data_t *  key
) 
 

Base implementation for dataset_lookup and dataset_lookupstr.

LIBGIFT_EXPORT DatasetNode* dataset_lookup_node (  Dataset *  d,
const void *  key,
size_t  key_len
) 
 

Lookup a complete set by the set's key. Similar to dataset_lookup except that the full set is returned.

LIBGIFT_EXPORT DatasetNode* dataset_lookup_node_ex (  Dataset *  d,
ds_data_t *  key
) 
 

Base implementation for dataset_lookup_node.

LIBGIFT_EXPORT void* dataset_lookupstr (  Dataset *  d,
const char *  key
) 
 

Wrapper around dataset_lookup for aggregate string constants.

EXTERN_C_BEGIN LIBGIFT_EXPORT Dataset* dataset_new (  DatasetType  type  ) 
 

Allocate a new dataset. Using this function is optional, see dataset_insert for more information.

Parameters:
type Backend implementation to use.

LIBGIFT_EXPORT void dataset_remove (  Dataset *  d,
const void *  key,
size_t  key_len
) 
 

Remove a key/value set by the key.

LIBGIFT_EXPORT void dataset_remove_ex (  Dataset *  d,
ds_data_t *  key
) 
 

Base implementation for dataset_remove and dataset_removestr.

LIBGIFT_EXPORT void dataset_remove_node (  Dataset *  d,
DatasetNode *  node
) 
 

Perform a remove operation from the original lookup node. No extra lookup will be performed.

LIBGIFT_EXPORT void dataset_removestr (  Dataset *  d,
const char *  key
) 
 

Wrapped around dataset_remove for string constants.

LIBGIFT_EXPORT uint32_t dataset_uniq32 (  Dataset *  d,
uint32_t *  counter
) 
 

Find a unique, non-zero 32-bit value that is not contained in the dataset. Assumes that the dataset contains integers.

Parameters:
d 
counter Hint variable for fast lookup.
Return values:
A unique, non-zero 32-bit integer that is not a key of the dataset.

LIBGIFT_EXPORT void ds_data_init (  ds_data_t *  dsdata,
const void *  data,
size_t  len,
int  flags
) 
 

Initialize a ds_data_t element for use with the extended dataset interface. Example usage:

 ds_data_t key;
 ds_data_t data;

 ds_data_init (&key, "foo", 4, DS_NOCOPY);
 ds_data_init (&data, "bar", 4, DS_NOCOPY);

 dataset_insert_ex (&d, &key, &data);

Parameters:
dsdata Storage location to initialize.
data Data to be attached with this element.
len Length of the data segment, or 0 if you wish to leave undefined (must set DS_NOCOPY).
flags Action-specific flags to use for the data element.

Generated on Sun Aug 22 08:07:10 2004 by doxygen 1.3.7