qf/quakeforge
0
0
Fork 0
mirror of https://git.code.sf.net/p/quake/quakeforge synced 2024-11-10 23:32:09 +00:00
Code Issues Projects Releases Packages Wiki Activity

fix the doxygen comments to produce proper docs

Browse source
This commit is contained in:
Bill Currie 2006-12-02 23:02:34 +00:00 committed by Jeff Teunissen
parent 7bca4cf8af
commit f37cfefc5a
1 changed files with 102 additions and 54 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

156
include/QF/hash.h
View file

@ -38,22 +38,22 @@
typedef struct hashtab_s hashtab_t; typedef struct hashtab_s hashtab_t;
/** create a new hash table: /** create a new hash table.
tsize: table size. larger values will give better distribution, but \param tsize table size. larger values will give better distribution, but
use more memory. use more memory.
gk: a function that returns a string to be used as the key for \param gk a function that returns a string to be used as the key for
inserting or finding the element. First parameter is a pointer inserting or finding the element. First parameter is a pointer
to the element from which to extract the key, the second is to the element from which to extract the key, the second is
the user data pointer. the user data pointer.
f: a function to free the element. Only ever called from \param f a function to free the element. Only ever called from
Hash_FlushTable and Hash_DelTable. The first parameter is the Hash_FlushTable and Hash_DelTable. The first parameter is the
element to be freed and the second is the user data pointer. element to be freed and the second is the user data pointer.
ud: user data pointer. set to whatever you want, it will be passed \param ud user data pointer. set to whatever you want, it will be passed
to the get key and free functions as the second parameter. to the get key and free functions as the second parameter.
returns a pointer to the hash table (to be passed to the other functions) \return pointer to the hash table (to be passed to the other functions)
or 0 on error. or 0 on error.
Hash_Add, Hash_Find, Hash_FindList and Hash_Del use gk and strcmp. Hash_Add(), Hash_Find(), Hash_FindList() and Hash_Del() use gk and strcmp.
multiple inserions of the same key are fine; later insertions override multiple inserions of the same key are fine; later insertions override
previous ones until the later one is removed (Hash_Del). previous ones until the later one is removed (Hash_Del).
@ -70,94 +70,142 @@ hashtab_t *Hash_NewTable (int tsize, const char *(*gk)(void*,void*),
be mixed with the non-element functions, but by default the results will be mixed with the non-element functions, but by default the results will
be undefined. be undefined.
gh takes the same parameters as gk above \param gh takes the same parameters as gk in Hash_NewTable
cmp is element 1, element 2, userdata \param cmp is element 1, element 2, userdata
*/ */
void Hash_SetHashCompare (hashtab_t *tab, unsigned long (*gh)(void*,void*), void Hash_SetHashCompare (hashtab_t *tab, unsigned long (*gh)(void*,void*),
int (*cmp)(void*,void*,void*)); int (*cmp)(void*,void*,void*));
/** delete a hash table: /** delete a hash table.
tab: the table to be deleted \param tab the table to be deleted
*/ */
void Hash_DelTable (hashtab_t *tab); void Hash_DelTable (hashtab_t *tab);
/** clean out all the entries from a hash table, starting over again: /** clean out all the entries from a hash table, starting over again.
tab: the table to be cleared \param tab the table to be cleared
*/ */
void Hash_FlushTable (hashtab_t *tab); void Hash_FlushTable (hashtab_t *tab);
//@{ /** add an entry to a hash table.
/** add an entry to a hash table: \param tab the table to be added to
tab: the table to be added to \param ele the element to add to the table
ele: the element to add to the table \return 0 for success, -1 for error.
returns 0 for success, -1 for error.
*/ */
int Hash_Add (hashtab_t *tab, void *ele); int Hash_Add (hashtab_t *tab, void *ele);
int Hash_AddElement (hashtab_t *tab, void *ele);
//@}
//@{ /** add an entry to a hash table.
/** find an element within a hash table: \param tab the table to be added to
tab: the table to search \param ele the element to add to the table
key: the key string identifying the element being searched for \return 0 for success, -1 for error.
returns a pointer to the element if found, otherwise 0. */
int Hash_AddElement (hashtab_t *tab, void *ele);
/** find an element within a hash table.
\param tab the table to search
\param key the key string identifying the element being searched for
\param ele element with info identifying the element being searched for
\return pointer to the element if found, otherwise 0.
*/ */
void *Hash_Find (hashtab_t *tab, const char *key); void *Hash_Find (hashtab_t *tab, const char *key);
void *Hash_FindElement (hashtab_t *tab, void *ele);
//@}
//@{ /** find an element within a hash table.
/** find a list of elements within a hash table: \param tab the table to search
tab: the table to search \param key the key string identifying the element being searched for
key: the key string identifying the elements being searched for \param ele element with info identifying the element being searched for
returns a null terminated list of element pointers if at least one found, \return pointer to the element if found, otherwise 0.
otherwise 0. returned list is guaranteed to be in reverse order of */
insertion. ie, deleting items from the list in list order will delete the void *Hash_FindElement (hashtab_t *tab, void *ele);
correct items.
/** find a list of elements within a hash table.
\param tab the table to search
\param key the key string identifying the elements being searched for
\return a null terminated list of element pointers if at least one
found, otherwise 0.
\note it is the caller's responsibilty to free() the list.
returned list is guaranteed to be in reverse order of insertion. ie,
deleting items from the list in list order will delete the correct items.
*/ */
void **Hash_FindList (hashtab_t *tab, const char *key); void **Hash_FindList (hashtab_t *tab, const char *key);
void **Hash_FindElementList (hashtab_t *tab, void *ele);
//@}
//@{ /** find a list of elements within a hash table.
/** delete an element from a hash table: \param tab the table to search
tab: the table to remove the element from \param ele element with info identifying the elements being searched for
key: the key string identifying the element to be deleted \return a null terminated list of element pointers if at least one
returns a pointer to the element on success, 0 if the element could not found, otherwise 0.
be found. \note it is the caller's responsibilty to free() the list.
Does /NOT/ call the free element function. That is the caller's
returned list is guaranteed to be in reverse order of insertion. ie,
deleting items from the list in list order will delete the correct items.
*/
void **Hash_FindElementList (hashtab_t *tab, void *ele);
/** delete an element from a hash table.
\param tab the table to remove the element from
\param key the key string identifying the element to be deleted
\return a pointer to the element on success, 0 if the element could not
be found.
Does \em NOT call the free element function. That is the caller's
responsibility. responsibility.
*/ */
void *Hash_Del (hashtab_t *tab, const char *key); void *Hash_Del (hashtab_t *tab, const char *key);
/** delete an element from a hash table.
\param tab the table to remove the element from
\param ele element with info identifying the element to be deleted
\return a pointer to the element on success, 0 if the element could not
be found.
Does \em NOT call the free element function. That is the caller's
responsibility.
*/
void *Hash_DelElement (hashtab_t *tab, void *ele); void *Hash_DelElement (hashtab_t *tab, void *ele);
//@}
/** calls the free element function for the supplied ele /** calls the free element function for the supplied ele
eg: \param tab the table associated with the element (for the free function)
Hash_Free (tab, Hash_Del (tab, key)); \param ele the element to be freed
eg: Hash_Free (tab, Hash_Del (tab, key));
*/ */
void Hash_Free (hashtab_t *tab, void *ele); void Hash_Free (hashtab_t *tab, void *ele);
/** returh the hash value of a string. this is the same function as used /** hash a string.
internally. \param str the string to hash
\return the hash value of the string.
this is the same function as used internally.
*/ */
unsigned long Hash_String (const char *str); unsigned long Hash_String (const char *str);
/** returh the hash value of a buffer. /** hash a buffer.
\param buf the buffer to hash
\param len the size of the buffer
\return the hash value of the string.
*/ */
unsigned long Hash_Buffer (const void *buf, int len); unsigned long Hash_Buffer (const void *buf, int len);
/** return the number of elements in the table. /** get the size of the table
\param tab the table in question
\return the number of elements in the table.
*/ */
size_t Hash_NumElements (hashtab_t *tab); size_t Hash_NumElements (hashtab_t *tab);
/** return a list of all elements in the table. it is the caller's /** list of all elements in the table.
responsibilty to free() the array. Null terminated. \param tab the table to list
\return a null terminated list of element pointers for all elements
in the table
\note it is the caller's responsibilty to free() the list.
returned list is guaranteed to be in reverse order of insertion for
elements with the same key. ie, deleting items from the list in list order
will delete the correct items.
*/ */
void **Hash_GetList (hashtab_t *tab); void **Hash_GetList (hashtab_t *tab);
/** dump statistics about the hash table /** dump statistics about the hash table
\param tab the table to dump
*/ */
void Hash_Stats (hashtab_t *tab); void Hash_Stats (hashtab_t *tab);