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