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