vhash.h File Reference


Detailed Description

A documented header file containing the vhash.

Definition in file vhash.h.

#include <stdlib.h>
#include "vlist.h"

Go to the source code of this file.

Classes

struct  vhash_s
struct  vhash_pair_s
struct  vhash_string_key_pair_s

Defines

#define VHASH_CDECL
#define VHASH_STATUS_FAILED   0
 A failure status.
#define VHASH_STATUS_SUCCESS   1
 A success status.
#define VHASH_STATUS_INSERTED   2
 A item was inserted.

Typedefs

typedef void *VHASH_CDECL * vmalloc_t (size_t)
typedef int vhash_status_t

Functions

_W3DTK_API vhash_tnew_vhash (unsigned long table_size, vmalloc_t vmalloc, vfree_t vfree)
 This function creates and initalises a vhash structure.
_W3DTK_API void delete_vhash (vhash_t *vhash)
 This function destroys and cleans up a vhash structure.
_W3DTK_API vhash_status_t vhash_rebuild_table (vhash_t *vhash, unsigned long table_size)
 This function rebuilds the hash a specifed size never rebuild less than 2*count.
_W3DTK_API unsigned long vhash_count (vhash_t *vhash)
 This function returns the number of items in the vhash.
_W3DTK_API void vhash_map_function (vhash_t *v, void(*function)(void *, void *, void *), void *user_data)
 This function calls a function once per item in the vhash. Your function returns VHASH_STATUS_SUCCESS to keep mapping. Your function returns VHASH_STATUS_FAILED to stop mapping.
_W3DTK_API vhash_status_t vhash_to_vlist (vhash_t *vhash, vlist_t *vlist, void *(VHASH_CDECL *vhash_pair_malloc)(size_t))
 This function builds a vlist of item key pairs.
_W3DTK_API vhash_status_t vhash_replace_item (vhash_t *v, void *in_key, void *new_item, void **replaced_item)
 This function replaces or adds a item to the vhash.
_W3DTK_API vhash_status_t vhash_insert_item (vhash_t *v, void *in_key, void *item)
 This function adds a item to the vhash.
_W3DTK_API vhash_status_t vhash_remove_item (vhash_t *v, void *in_key, void **removed_item)
 This function removes an item from the vhash.
_W3DTK_API vhash_status_t vhash_lookup_item (const vhash_t *v, void *in_key, void **out_item)
 This function looks up an item from the vhash.
_W3DTK_API vhash_status_t vhash_lookup_nth_item (const vhash_t *v, void *in_key, int n, void **out_item)
 This function behaves exactly like vhash_lookup_item, except it skips a number of matches equal to the given 'n'. When hash keys are not guaranteed to be unique, this function allows access to all of the items that match a given key.
_W3DTK_API void vhash_string_key_map_function (vhash_t *v, void(*function)(void *, const char *, void *), void *user_data)
 This function calls a function once per item in the vhash. The keys are strings. Your function returns VHASH_STATUS_SUCCESS to keep mapping. Your function returns VHASH_STATUS_FAILED to stop mapping.
_W3DTK_API vhash_status_t vhash_replace_string_key_item (vhash_t *v, const char *string_key, void *new_item, void **replaced_item)
 This function replaces or adds a item to the vhash. The keys are strings. replaced_item is valid only if return status is VHASH_STATUS_SUCCESS returns VHASH_STATUS_INSERTED is no item with same key existed.
_W3DTK_API vhash_status_t vhash_insert_string_key_item (vhash_t *v, const char *string_key, void *item)
 This function adds a item to the vhash. The keys are strings.
_W3DTK_API vhash_status_t vhash_remove_string_key_item (vhash_t *v, const char *string_key, void **removed_item)
 This function removes an item from the vhash. The keys are strings.
_W3DTK_API vhash_status_t vhash_lookup_string_key_item (vhash_t *v, const char *string_key, void **out_item)
 This function looks up an item from the vhash. The keys are strings.
_W3DTK_API vhash_status_t vhash_lookup_nth_string_key_item (vhash_t *v, const char *string_key, int n, void **out_item)
 This function behaves exactly like vhash_lookup_string_key_item, except it skips a number of matches equal to the given 'n'. When hash keys are not guaranteed to be unique, this function allows access to all of the items that match a given key. The keys are strings.
_W3DTK_API vhash_status_t vhash_string_keys_to_vlist (vhash_t *vhash, vlist_t *vlist, void *(VHASH_CDECL *vhash_pair_malloc)(size_t))
 This function builds a string key item pair from the vhash.


Typedef Documentation

typedef void* VHASH_CDECL* vmalloc_t(size_t)
 

The vhash is a linear probing hash.

This vhash assumes all keys are unique. If not remove the old key/item first the add the new one.

The vhash can operate on void pointers or string keys. Do not mix these uses.

This auto resizes at 50% capacity for best perfomance choose a size 2*max items expected.

Definition at line 39 of file vhash.h.


Function Documentation

_W3DTK_API void delete_vhash vhash_t vhash  ) 
 

This function destroys and cleans up a vhash structure.

Parameters:
vhash The vhash to delete

_W3DTK_API vhash_t* new_vhash unsigned long  table_size,
vmalloc_t  vmalloc,
vfree_t  vfree
 

This function creates and initalises a vhash structure.

Parameters:
table_size How big to create the hash (greater than 0 please)
vmalloc A malloc function for vhash to use
vfree A free function for vhash to use
Returns:
The vhash structure

_W3DTK_API unsigned long vhash_count vhash_t vhash  ) 
 

This function returns the number of items in the vhash.

Parameters:
vhash The vhash to operate on
Returns:
The number of items in the vhash

_W3DTK_API vhash_status_t vhash_insert_item vhash_t v,
void *  in_key,
void *  item
 

This function adds a item to the vhash.

Parameters:
v The vhash to operate on
in_key A item key
item The item to add to the vhash
Returns:
a vhash_status_t the result of the action (returns VHASH_STATUS_SUCCESS always)

_W3DTK_API vhash_status_t vhash_insert_string_key_item vhash_t v,
const char *  string_key,
void *  item
 

This function adds a item to the vhash. The keys are strings.

Parameters:
v The vhash to operate on
string_key A null terminated item key
item The item to add to the vhash
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_lookup_item const vhash_t v,
void *  in_key,
void **  out_item
 

This function looks up an item from the vhash.

Parameters:
v The vhash to operate on
in_key A item key
out_item A pointer to a void pointer that a looked up item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_lookup_nth_item const vhash_t v,
void *  in_key,
int  n,
void **  out_item
 

This function behaves exactly like vhash_lookup_item, except it skips a number of matches equal to the given 'n'. When hash keys are not guaranteed to be unique, this function allows access to all of the items that match a given key.

Parameters:
v The vhash to operate on
in_key A item key
n The number of matches to skip
out_item A pointer to a void pointer that a looked up item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_lookup_nth_string_key_item vhash_t v,
const char *  string_key,
int  n,
void **  out_item
 

This function behaves exactly like vhash_lookup_string_key_item, except it skips a number of matches equal to the given 'n'. When hash keys are not guaranteed to be unique, this function allows access to all of the items that match a given key. The keys are strings.

Parameters:
v The vhash to operate on
string_key A null terminated item key
n The number of matches to skip
out_item A pointer to a void pointer that a looked up item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_lookup_string_key_item vhash_t v,
const char *  string_key,
void **  out_item
 

This function looks up an item from the vhash. The keys are strings.

Parameters:
v The vhash to operate on
string_key A null terminated item key
out_item A pointer to a void pointer that a looked up item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API void vhash_map_function vhash_t v,
void(*)(void *, void *, void *)  function,
void *  user_data
 

This function calls a function once per item in the vhash. Your function returns VHASH_STATUS_SUCCESS to keep mapping. Your function returns VHASH_STATUS_FAILED to stop mapping.

Parameters:
v The vhash to operate on
function The function to call (item,key,user_data)
user_data A void pointer to pass with each item

_W3DTK_API vhash_status_t vhash_rebuild_table vhash_t vhash,
unsigned long  table_size
 

This function rebuilds the hash a specifed size never rebuild less than 2*count.

Parameters:
vhash The vhash to operate on
table_size The new size
Returns:
a vhash_status_t the result of the rebuild

_W3DTK_API vhash_status_t vhash_remove_item vhash_t v,
void *  in_key,
void **  removed_item
 

This function removes an item from the vhash.

Parameters:
v The vhash to operate on
in_key A item key
removed_item A pointer to a void pointer that a removed item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_remove_string_key_item vhash_t v,
const char *  string_key,
void **  removed_item
 

This function removes an item from the vhash. The keys are strings.

Parameters:
v The vhash to operate on
string_key A null terminated item key
removed_item A pointer to a void pointer that a removed item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_replace_item vhash_t v,
void *  in_key,
void *  new_item,
void **  replaced_item
 

This function replaces or adds a item to the vhash.

Parameters:
v The vhash to operate on
in_key A item key
new_item The item to add to the vhash
replaced_item A pointer to a void pointer that a replaced item can be write to
Returns:
a vhash_status_t the result of the action (returns VHASH_STATUS_SUCCESS always)

_W3DTK_API vhash_status_t vhash_replace_string_key_item vhash_t v,
const char *  string_key,
void *  new_item,
void **  replaced_item
 

This function replaces or adds a item to the vhash. The keys are strings. replaced_item is valid only if return status is VHASH_STATUS_SUCCESS returns VHASH_STATUS_INSERTED is no item with same key existed.

Parameters:
v The vhash to operate on
string_key A null terminated item key
new_item The item to add to the vhash
replaced_item A pointer to a void pointer that a replaced item can be write to
Returns:
a vhash_status_t the result of the action

_W3DTK_API void vhash_string_key_map_function vhash_t v,
void(*)(void *, const char *, void *)  function,
void *  user_data
 

This function calls a function once per item in the vhash. The keys are strings. Your function returns VHASH_STATUS_SUCCESS to keep mapping. Your function returns VHASH_STATUS_FAILED to stop mapping.

Parameters:
v The vhash to operate on
function The function to call (item,key,user_data)
user_data A void pointer to pass with each item

_W3DTK_API vhash_status_t vhash_string_keys_to_vlist vhash_t vhash,
vlist_t vlist,
void *  (VHASH_CDECL *vhash_pair_malloc)(size_t)
 

This function builds a string key item pair from the vhash.

Parameters:
vhash The vhash to operate on
vlist A vlist to populate with string key item pairs
(VHASH_CDECL *vhash_pair_malloc) A malloc function to user to allocate the key item pairs
Returns:
a vhash_status_t the result of the action

_W3DTK_API vhash_status_t vhash_to_vlist vhash_t vhash,
vlist_t vlist,
void *  (VHASH_CDECL *vhash_pair_malloc)(size_t)
 

This function builds a vlist of item key pairs.

Parameters:
vhash The vhash to operate on
vlist A vlist to populate with key item pairs
vhash_pair_malloc A malloc function to user to allocate the key item pairs
Returns:
a vhash_status_t the result of the action


Generated on Tue Jan 6 22:41:37 2009 for Autodesk DWF 3D Toolkit by  doxygen 1.4.5