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

gi_dataset.h File Reference

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

#include "gi_list.h"
#include "array.h"

Go to the source code of this file.

Classes

struct  ds_data_t
struct  gi_dataset_node

Defines

#define DS_NOCOPY   0x01
#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_RETURN(ret)   ((ret) & 0x03)
#define DS_FOREACH(func)   ((GiDatasetForeachFn)func)
#define DS_FOREACH_EX(func)   ((GiDatasetForeachExFn)func)
#define DS_FIND(func)   ((GiDatasetFindFn)func)

Typedefs

typedef gi_dataset_node GiDatasetNode
typedef gi_dataset GiDataset
typedef void(* GiDatasetForeachFn )(ds_data_t *key, ds_data_t *value, void *udata)
typedef int(* GiDatasetForeachExFn )(ds_data_t *key, ds_data_t *value, void *udata)
typedef GiDatasetForeachExFn GiDatasetFindFn

Enumerations

enum  GiDatasetType { GI_DATASET_LIST, GI_DATASET_ARRAY, GI_DATASET_HASH, GI_DATASET_DEFAULT = GI_DATASET_HASH }

Functions

EXTERN_C_BEGIN LIBGIFT_EXPORT
GiDataset * 		gi_dataset_new (GiDatasetType type)
LIBGIFT_EXPORT void gi_dataset_clear (GiDataset *d)
LIBGIFT_EXPORT void gi_dataset_destroy (GiDataset **d)
LIBGIFT_EXPORT void ds_data_init (ds_data_t *dsdata, const void *data, size_t len, int flags)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_insert_ex (GiDataset **d, ds_data_t *key, ds_data_t *value)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_insert (GiDataset **d, const void *key, size_t key_len, const void *value, size_t value_len)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_insertstr (GiDataset **d, const char *key, const char *value)
LIBGIFT_EXPORT void gi_dataset_remove_ex (GiDataset *d, ds_data_t *key)
LIBGIFT_EXPORT void gi_dataset_remove (GiDataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void gi_dataset_removestr (GiDataset *d, const char *key)
LIBGIFT_EXPORT void gi_dataset_remove_node (GiDataset *d, GiDatasetNode *node)
LIBGIFT_EXPORT ds_data_t * gi_dataset_lookup_ex (GiDataset *d, ds_data_t *key)
LIBGIFT_EXPORT void * gi_dataset_lookup (GiDataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void * gi_dataset_lookupstr (GiDataset *d, const char *key)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_lookup_node_ex (GiDataset *d, ds_data_t *key)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_lookup_node (GiDataset *d, const void *key, size_t key_len)
LIBGIFT_EXPORT void gi_dataset_foreach (GiDataset *d, GiDatasetForeachFn func, void *udata)
LIBGIFT_EXPORT void gi_dataset_foreach_ex (GiDataset *d, GiDatasetForeachExFn func, void *udata)
LIBGIFT_EXPORT void * gi_dataset_find (GiDataset *d, GiDatasetFindFn func, void *udata)
LIBGIFT_EXPORT GiDatasetNode * gi_dataset_find_node (GiDataset *d, GiDatasetFindFn func, void *udata)
LIBGIFT_EXPORT unsigned int gi_dataset_length (GiDataset *d)
LIBGIFT_EXPORT GiList * gi_dataset_flatten (GiDataset *d)
LIBGIFT_EXPORT uint32_t gi_dataset_uniq32 (GiDataset *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   )     ((GiDatasetForeachFn)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(* GiDatasetForeachExFn)(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(* GiDatasetForeachFn)(ds_data_t *key, ds_data_t *value, void *udata)
 

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

typedef struct gi_dataset_node GiDatasetNode
 

Describes a specific key/value set.

Enumeration Type Documentation

enum GiDatasetType
 

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

Enumeration values:
GI_DATASET_LIST  Linked list
GI_DATASET_ARRAY  Dynamically allocated array
GI_DATASET_HASH  Hash table

Function Documentation

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

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

LIBGIFT_EXPORT void gi_dataset_clear (  GiDataset *  d  ) 
 

Clear all internally allocated data entries, but do not destroy the dataset handle itself.

LIBGIFT_EXPORT void gi_dataset_destroy (  GiDataset **  d  ) 
 

Unallocate a dataset and clear all internally allocated data members.

LIBGIFT_EXPORT void* gi_dataset_find (  GiDataset *  d,
GiDatasetFindFn  func,
void *  udata
) 
 

Locate a set value through iteration. See gi_dataset_find_node.

Returns:
Pointer to the value entry found.

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_find_node (  GiDataset *  d,
GiDatasetFindFn  func,
void *  udata
) 
 

Locate a dataset node through iteration. GiDatasetForeach returns true when the set has been found.

LIBGIFT_EXPORT GiList* gi_dataset_flatten (  GiDataset *  d  ) 
 

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

LIBGIFT_EXPORT void gi_dataset_foreach (  GiDataset *  d,
GiDatasetForeachFn  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 gi_dataset_foreach_ex.

LIBGIFT_EXPORT void gi_dataset_foreach_ex (  GiDataset *  d,
GiDatasetForeachExFn  func,
void *  udata
) 
 

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

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_insert (  GiDataset **  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 GI_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 gi_dataset_clear will not free this address.
Returns:
Node handle that has just been inserted, or NULL on error.

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_insert_ex (  GiDataset **  d,
ds_data_t *  key,
ds_data_t *  value
) 
 

Base implementation for gi_dataset_insert and gi_dataset_insertstr.

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_insertstr (  GiDataset **  d,
const char *  key,
const char *  value
) 
 

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

LIBGIFT_EXPORT unsigned int gi_dataset_length (  GiDataset *  d  ) 
 

Calculate the dataset length (total number of sets currently inserted). Please note that the GI_gi_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* gi_dataset_lookup (  GiDataset *  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 gi_dataset_lookup_node.

LIBGIFT_EXPORT ds_data_t* gi_dataset_lookup_ex (  GiDataset *  d,
ds_data_t *  key
) 
 

Base implementation for gi_dataset_lookup and gi_dataset_lookupstr.

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_lookup_node (  GiDataset *  d,
const void *  key,
size_t  key_len
) 
 

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

LIBGIFT_EXPORT GiDatasetNode* gi_dataset_lookup_node_ex (  GiDataset *  d,
ds_data_t *  key
) 
 

Base implementation for gi_dataset_lookup_node.

LIBGIFT_EXPORT void* gi_dataset_lookupstr (  GiDataset *  d,
const char *  key
) 
 

Wrapper around gi_dataset_lookup for aggregate string constants.

EXTERN_C_BEGIN LIBGIFT_EXPORT GiDataset* gi_dataset_new (  GiDatasetType  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 gi_dataset_remove (  GiDataset *  d,
const void *  key,
size_t  key_len
) 
 

Remove a key/value set by the key.

LIBGIFT_EXPORT void gi_dataset_remove_ex (  GiDataset *  d,
ds_data_t *  key
) 
 

Base implementation for gi_dataset_remove and gi_dataset_removestr.

LIBGIFT_EXPORT void gi_dataset_remove_node (  GiDataset *  d,
GiDatasetNode *  node
) 
 

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

LIBGIFT_EXPORT void gi_dataset_removestr (  GiDataset *  d,
const char *  key
) 
 

Wrapped around gi_dataset_remove for string constants.

LIBGIFT_EXPORT uint32_t gi_dataset_uniq32 (  GiDataset *  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.

Generated on Sun Aug 22 07:56:40 2004 by doxygen 1.3.7