quakeforge/include/QF/hash.h

151 lines
4.4 KiB
C
Raw Normal View History

/*
hash.h
hash tables
Copyright (C) 2000 Bill Currie <bill@taniwha.org>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to:
Free Software Foundation, Inc.
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA
$Id$
*/
#ifndef __hash_h
#define __hash_h
2001-06-11 19:17:40 +00:00
typedef struct hashtab_s hashtab_t;
/*
create a new hash table:
tsize: table size. larger values will give better distribution, but
use more memory.
gk: a function that returns a string to be used as the key for
inserting or finding the element. First parameter is a pointer
to the element from which to extract the key, the second is
the user data pointer.
f: a function to free the element. Only ever called from
Hash_FlushTable and Hash_DelTable. The first parameter is the
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
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)
or 0 on error.
multiple inserions of the same key are fine; later insertions override
previous ones until the later one is removed (Hash_Del).
*/
hashtab_t *Hash_NewTable (int tsize, const char *(*gk)(void*,void*),
void (*f)(void*,void*), void *ud);
/*
change the hash and compare functions used by the Has_*Element functions.
the default hash function just returns the address of the element, and the
default compare just compares the addresses. compare is to return 0 for not
equal and non-0 otherwise.
gh takes the same parameters as gk above
cmp is element 1, element 2, userdata
*/
void Hash_SetHashCompare (hashtab_t *tab, unsigned long (*gh)(void*,void*),
int (*cmp)(void*,void*,void*));
/*
delete a hash table:
tab: the table to be deleted
*/
void Hash_DelTable (hashtab_t *tab);
/*
clean out all the entries from a hash table, starting over again:
tab: the table to be cleared
*/
void Hash_FlushTable (hashtab_t *tab);
/*
add an entry to a hash table:
tab: the table to be added to
ele: the element to add to the table
returns 0 for success, -1 for error.
*/
int Hash_Add (hashtab_t *tab, void *ele);
int Hash_AddElement (hashtab_t *tab, void *ele);
/*
find an element within a hash table:
tab: the table to search
key: the key string identifying the element being searched for
returns a pointer to the element if found, otherwise 0.
*/
void *Hash_Find (hashtab_t *tab, const char *key);
void *Hash_FindElement (hashtab_t *tab, void *ele);
/*
find a list of elements within a hash table:
tab: the table to search
key: the key string identifying the elements being searched for
returns a null terminated list of element pointers if at least one found,
otherwise 0.
*/
void **Hash_FindList (hashtab_t *tab, const char *key);
void **Hash_FindElementList (hashtab_t *tab, void *ele);
/*
delete an element from a hash table:
tab: the table to remove the element from
key: the key string identifying the element to be deleted
returns a pointer to the element on success, 0 if the element could not
be found.
Does /NOT/ call the free element function. That is the caller's
responsibility.
*/
void *Hash_Del (hashtab_t *tab, const char *key);
void *Hash_DelElement (hashtab_t *tab, void *ele);
2003-02-21 02:37:44 +00:00
/*
calls the free element function for the supplied ele
eg:
Hash_Free (tab, Hash_Del (tab, key));
*/
void Hash_Free (hashtab_t *tab, void *ele);
/*
returh the hash value of a string. this is the same function as used
internally.
*/
unsigned long Hash_String (const char *str);
/*
returh the hash value of a buffer.
*/
unsigned long Hash_Buffer (const void *buf, int len);
/*
return a list of all elements in the table. it is the caller's
responsibilty to free() the array. Null terminated.
*/
void **Hash_GetList (hashtab_t *tab);
/*
dump statistics about the hash table
*/
void Hash_Stats (hashtab_t *tab);
#endif // __hash_h