a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A hashing function.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in/out] cdata Opaque data that can be passed to HtInit that will
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync eventually end up here
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] ptr The data to be hashed. The size of the data, if
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync needed, can be configured via a record that can be
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync passed via cdata.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] numBits The number of bits this hash needs to have in the
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync resulting hash
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @return A numBits-bit hash of the data
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsynctypedef unsigned (*HashFunc)(void * cdata, const void * ptr, int numBits);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A comparison function for hashed keys.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in/out] cdata Opaque data that ca be passed to Htinit that will
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync eventually end up here
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] l The left side data to be compared
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] r The right side data to be compared
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @return -1 if l < r, 0 if l == r, 1 if l > r
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsynctypedef int (*HashCompareFunc)(void * cdata, const void * l, const void * r);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A configuration for HtGenericHash */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsynctypedef struct {
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief ht_create initalizes a hash table for a certain hash table
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync configuration
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[out] ht The hash table structure to initialize
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] keySize The key size in bytes
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] dataSize The data size in bytes
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] hash The hash function to use for hashing keys
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] compare The comparison function for hashing keys
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in] cdata Opaque data that will be passed to hash and
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync comparison functions
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief HtDestruct deinitializes the structure. It does not free the
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync memory allocated to HashTableRec
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief Adds a new key to the hash table. The key will be copied
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync and a pointer to the value will be returned. The data will
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync be initialized with zeroes.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[in/out] ht The hash table
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @param[key] key The key. The contents of the key will be copied.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @return On error NULL is returned, otherwise a pointer to the data
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync associated with the newly inserted key.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @note If dataSize is 0, a pointer to the end of the key may be returned
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync to avoid returning NULL. Obviously the data pointed cannot be
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync modified, as implied by dataSize being 0.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT pointer ht_add(HashTable ht, pointer key);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief Removes a key from the hash table along with its
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync associated data, which will be free'd.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT void ht_remove(HashTable ht, pointer key);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief Finds the associated data of a key from the hash table.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @return If the key cannot be found, the function returns NULL.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync Otherwise it returns a pointer to the data associated
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync with the key.
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync @note If dataSize == 0, this function may return NULL
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync even if the key has been inserted! If dataSize == NULL,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync use HtMember instead to determine if a key has been
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT pointer ht_find(HashTable ht, pointer key);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A generic hash function */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT unsigned ht_generic_hash(void *cdata,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void *ptr,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A generic comparison function. It compares data byte-wise. */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT int ht_generic_compare(void *cdata,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void *l,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void *r);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A debugging function that dumps the distribution of the
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync hash table: for each bucket, list the number of elements
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync contained within. */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT void ht_dump_distribution(HashTable ht);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A debugging function that dumps the contents of the hash
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync table: for each bucket, list the elements contained
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT void ht_dump_contents(HashTable ht,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A hashing function to be used for hashing resource IDs when
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync used with HashTables. It makes no use of cdata, so that can
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync be NULL. It uses HashXID underneath, and should HashXID be
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync unable to hash the value, it switches into using the generic
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync hash function. */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT unsigned ht_resourceid_hash(void *cdata,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void * data,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync/** @brief A comparison function to be used for comparing resource
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync IDs when used with HashTables. It makes no use of cdata,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync so that can be NULL. */
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsyncextern _X_EXPORT int ht_resourceid_compare(void *cdata,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void *a,
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync const void *b);
a3f3701cea1ba388e7c877955252bb7375eedebdvboxsync#endif // HASHTABLE_H