/ 
MarpaX-ESLIF-2.0.40
River stage one • 2 direct dependents • 4 total dependents
/ genericHash
Travis CI build status GitHub version License MIT

NAME

genericHash - generic hash interface

DESCRIPTION

genericHash is an ANSI set of macros exposing key hashing and comparison functions, as well as key/value copying and freeing functions. It is built on top of genericStack.

SYNOPSIS

#include <genericHash.h>

genericHash_t *myHashp;

MACROS

GENERICHASH_NEW(hashName, indFunctionp)

Alias to GENERICHASH_NEW_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.

GENERICHASH_NEW_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize)

Create an empty hash on the heap, where function pointer prototypes are:

typedef size_t (*genericHashKeyIndFunction_t)(void *userDatavp, genericStackItemType_t itemType, void **pp);
typedef short  (*genericHashKeyCmpFunction_t)(void *userDatavp, void **pp1, void **pp2);
typedef void  *(*genericHashKeyCopyFunction_t)(void *userDatavp, void **pp);
typedef void   (*genericHashKeyFreeFunction_t)(void *userDatavp, void **pp);
typedef void  *(*genericHashValCopyFunction_t)(void *userDatavp, void **pp);
typedef void   (*genericHashValFreeFunction_t)(void *userDatavp, void **pp);

All these functions are called with a context userDatavp that is passed as-is through macros described below. The generic pointers are always pointers to data, i.e. pointer to char, pointer to pointer, etc... Take care, nothing prevent the pointer content to be a NULL pointer itself, depending on the context (see below).

keyIndFunctionp
typedef size_t (*genericHashKeyIndFunction_t)(void *userDatavp, genericStackItemType_t itemType, void **pp);

Mandatory. This function returns the indice in the hash. itemType is generated using genericStack constants, e.g. it can be GENERICSTACKITEMTYPE_CHAR, GENERICSTACKITEMTYPE_PTR, etc... *pp is a pointer to the data, regardless of its type, i.e. it can be a pointer to char, a pointer to a pointer, etc...

keyCmpFunctionp
typedef short  (*genericHashKeyCmpFunction_t)(void *userDatavp, void **pp1, void **pp2);

Optional. When not NULL, this function is called only when the engine need to know if two opaque pointers refer to identical objects, and to handle collisions within the same hash row. This mean that the item type is implicitly GENERICSTACKITEMTYPE_PTR, and the function is called with two pointers of pointer. If the function returns a true value, the two keys are considered equal. If this function pointer is NULL, direct pointer comparison is done.

keyCopyFunctionp
typedef void  *(*genericHashKeyCopyFunction_t)(void *userDatavp, void **pp);

Optional. When not NULL, this function is called only when the engine need to insert data that is an opaque pointer. This mean that the item type is implicitly GENERICSTACKITEMTYPE_PTR. This function must return a non NULL if the data pointed to by *p is non NULL. If this function pointer is NULL, direct pointer copy is done.

keyFreeFunctionp
typedef void   (*genericHashKeyFreeFunction_t)(void *userDatavp, void **pp);

Optional. When not NULL, this is called only when the engine need to free data that is an opaque pointer.

valCopyFunctionp
typedef void  *(*genericHashValCopyFunction_t)(void *userDatavp, void **pp);

Optional. Same description as keyCopyFunctionp, but for values.

valFreeFunctionp
typedef void   (*genericHashValFreeFunction_t)(void *userDatavp, void **pp);

Optional. Same description as keyFreeFunctionp, but for values.

wantedSize

Optional. Initial number of hash rows.

wantedSubSize

Optional. Initial number of columns within a hash row.

GENERICHASH_INIT(hashName, indFunctionp)

Alias to GENERICHASH_INIT_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.

GENERICHASH_INIT_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize)

Create an empty hash on the stack, where function pointer prototypes have the same meaning as in GENERICHASH_NEW_ALL.

GENERICHASH_SET(hashName, userDatavp, keyType, keyVal, valType, valVal)

Set an entry in hash hashName, using the key keyVal of type keyType, and value valVal of type valType. keyType and valType must be shorthands for genericStack constants, i.e. CHAR, PTR, etc...

GENERICHASH_SET_BY_IND(hashName, userDatavp, keyType, keyVal, valType, valVal, subStackIndex)

Same as GENERICHASH_SET, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.

GENERICHASH_FIND(hashName, userDatavp, keyType, keyVal, valType, valValp, findResult)

Find an entry in hash hashName, using the key keyVal of type keyType, and expecting a value of type valType. valValp must be a pointer, eventually NULL. If successful, the content of valValp is filled with the found value. findResult must be a valid C identifier, in which a true or a false will be set. keyType and valType must be shorthands for genericStack constants, i.e. CHAR, PTR, etc...

GENERICHASH_FIND_BY_IND(hashName, userDatavp, keyType, keyVal, valType, valValp, findResult, index)

Same as GENERICHASH_FIND, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.

GENERICHASH_REMOVE(hashName, userDatavp, keyType, keyVal, valType, valValp, findResult)

Remove an entry in hash hashName, using the key keyVal of type keyType, and expecting a value of type valType. valValp must be a pointer, eventually NULL. If successful, the content of valValp is filled with the found value. When valValp is NULL, key and data are explicitely removed, eventually calling the free callback functions. keyType and valType must be shorthands for genericStack constants, i.e. CHAR, PTR, etc...

GENERICHASH_REMOVE_BY_IND(hashName, userDatavp, keyType, keyVal, valType, valValp, findResult, index)

Same as GENERICHASH_REMOVE, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.

GENERICHASH_FREE(hashName)

Releases a hash allocated on the heap via GENERICHASH_NEW_ALL. This may call the free callback functions.

GENERICHASH_RESET(hashName)

Releases a hash initialized on the stack via GENERICHASH_INIT_ALL. This may call the free callback functions.

GENERICHASH_RELAX(hashName)

Sets back the hash to its initial state, without releasing all internal allocated memory. This is the most efficient way to <reuse> a hash.

GENERICHASH_ERROR(hashName)

Returns a true value if the hash an error, a false value otherwise.

GENERICHASH_USED(hashName)

Returns the number of elements in the hash. Take case, also it is legal from syntax point of view to use it an a lvalue, do not modify it.

GENERICHASH_KEYCMPFUNCTION(hashName)

Accessor to the key comparison function.

GENERICHASH_KEYCOPYFUNCTION(hashName)

Accessor to the key copy function.

GENERICHASH_KEYFREEFUNCTION(hashName)

Accessor to the key free function.

GENERICHASH_VALCOPYFUNCTION(hashName)

Accessor to the val copy function.

GENERICHASH_VALFREEFUNCTION(hashName)

Accessor to the val free function.

SEE ALSO

genericStack