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