NAME

genericSparseArray - generic sparse array interface

DESCRIPTION

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.

SYNOPSIS

  #include <genericSparseArray.h>

  genericSparseArray_t *mySparseArrayp;

MACROS

GENERICSPARSEARRAY_NEW(sparseArrayName, keyIndFunctionp)

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

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.

GENERICSPARSEARRAY_INIT(sparseArrayName, keyIndFunctionp)

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.

GENERICSPARSEARRAY_SET(sparseArrayName, userDatavp, indice, valType, valVal)

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

GENERICSPARSEARRAY_FIND(sparseArrayName, userDatavp, keyVal, valType, valValp, findResult)

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

GENERICSPARSEARRAY_FREE(sparseArrayName, useDatavp)

Releases a sparse array allocated on the heap. This may call the free callback functions.

GENERICSPARSEARRAY_RESET(sparseArrayName, useDatavp)

Releases a sparse array initialized on the stack. This may call the free callback functions.

GENERICSPARSEARRAY_RELAX(sparseArrayName, useDatavp)

Releases partially the array, so that it can be reused. More efficient than recreating the array in case of reuse.

GENERICSPARSEARRAY_USED(sparseArrayName)

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

GENERICSPARSEARRAY_ERROR(sparseArrayName)