genericHash - generic hash interface
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.
#include <genericHash.h> genericHash_t *myHashp;
Alias to GENERICHASH_NEW_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.
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).
userDatavp
NULL
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...
itemType
GENERICSTACKITEMTYPE_CHAR
GENERICSTACKITEMTYPE_PTR
*pp
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.
*p
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.
Alias to GENERICHASH_INIT_ALL(hashName, keyIndFunctionp, keyCmpFunctionp, keyCopyFunctionp, keyFreeFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.
Create an empty hash on the stack, where function pointer prototypes have the same meaning as in GENERICHASH_NEW_ALL.
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...
hashName
keyVal
keyType
valVal
valType
CHAR
PTR
Same as GENERICHASH_SET, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.
subStackIndex
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...
valValp
findResult
Same as GENERICHASH_FIND, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.
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...
Same as GENERICHASH_REMOVE, but bypasses the call to key indice function, by setting it explicitely in the subStackIndex variable.
Releases a hash allocated on the heap via GENERICHASH_NEW_ALL. This may call the free callback functions.
Releases a hash initialized on the stack via GENERICHASH_INIT_ALL. This may call the free callback functions.
Sets back the hash to its initial state, without releasing all internal allocated memory. This is the most efficient way to <reuse> a hash.
Returns a true value if the hash an error, a false value otherwise.
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.
Accessor to the key comparison function.
Accessor to the key copy function.
Accessor to the key free function.
Accessor to the val copy function.
Accessor to the val free function.
genericStack
To install MarpaX::ESLIF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MarpaX::ESLIF
CPAN shell
perl -MCPAN -e shell install MarpaX::ESLIF
For more information on module installation, please visit the detailed CPAN module installation guide.