genericSparseArray - generic sparse array interface
genericSparseArray is an ANSI set of macros implementing sparse array. It is built on top of genericHash, and exposes key hashing, as well as value copying and freeing functions. Since internal storage is based on hashing, there is no limitation on the array indice number, this mean that negative indices are supported.
#include <genericSparseArray.h>
genericSparseArray_t *mySparseArrayp;
Alias to GENERICSPARSEARRAY_NEW_ALL(sparseArrayName, keyIndFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.
GENERICSPARSEARRAY_NEW_ALL(sparseArrayName, keyIndFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize)
Create an empty sparse array on the heap, where function pointer prototypes are shared with genericHash, i.e.:
typedef size_t (*genericHashKeyIndFunction_t)(void *userDatavp, genericStackItemType_t itemType, 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 beGENERICSTACKITEMTYPE_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... valCopyFunctionp
-
typedef void *(*genericHashValCopyFunction_t)(void *userDatavp, void **pp);
Optional. May be called if the value is a PTR. Must return a non-NULL value if
*pp
is non-NULL. valFreeFunctionp
-
typedef void (*genericHashValFreeFunction_t)(void *userDatavp, void **pp);
Optional. May be called if the value is a PTR. Nothing prevent
*pp
to be NULL. wantedSize
-
Optional. Initial number of hash rows.
wantedSubSize
-
Optional. Initial number of columns within a hash row.
Alias to GENERICSPARSEARRAY_INIT_ALL(sparseArrayName, keyIndFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize), see below.
GENERICSPARSEARRAY_INIT_ALL(sparseArrayName, keyIndFunctionp, valCopyFunctionp, valFreeFunctionp, wantedSize, wantedSubSize)
Create an empty sparse array on the stack, where function pointer prototypes have the same meaning as in GENERICSPARSEARRAY_NEW.
Set an entry in the array sparseArrayName
at indice keyVal
, and value valVal
of type valType
. keyType
and valType
must be shorthands for genericStack constants, i.e. CHAR
, PTR
, etc...
Find an entry in the array sparseArrayName
at indice keyVal
, 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...
GENERICSPARSEARRAY_REMOVE(sparseArrayName, userDatavp, indice, keyVal, valType, valValp, findResult)
Remove an entry in the array sparseArrayName
at indice keyVal
, 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...
Releases a sparse array allocated on the heap. This may call the free callback functions.
Releases a sparse array initialized on the stack. This may call the free callback functions.
Releases partially the array, so that it can be reused. More efficient than recreating the array in case of reuse.
Returns a true value if the array has an error, a false value otherwise.
Returns a true value if the array has an error, a false value otherwise.
Accessor to the val copy function.
Accessor to the val free function.