Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals   Examples  

chtbl.c File Reference

Go to the source code of this file.

Functions

int chtbl_init (CHTbl *htab, int conteneurs, int(*h)(const void *cle), int(*corresp)(const void *cle1, const void *cle2), void(*detruire)(void *donnee))
 Initialize the hash table. This function must be called first.

void chtbl_destroy (CHTbl *htab)
 Free all memory allocated for the hash table.

int chtbl_insert (CHTbl *htab, const void *donnee)
 Insert data into the hash table.

int chtbl_remove (CHTbl *htab, void **donnee)
 Remove a record from the hash table.

int chtbl_lookup (const CHTbl *htab, void **donnee)
 Searh the hash table for a given data.

int chtbl_find (const CHTbl *htab, void **donnee)
 Cover the entire hash table in search for an given element.

void * chtbl_next (CHTbl *htab, int rewind)
 Returns the next element of a given linked list.


Detailed Description

Hash table implementation

Definition in file chtbl.c.


Function Documentation

void chtbl_destroy CHTbl   htab
 

Free all memory allocated for the hash table.

Parameters:
htab Pointer to the hash table data structure to destroy.
Examples:
test_hash_table.c.

Definition at line 66 of file chtbl.c.

References CHTbl_::conteneurs, list_destroy(), and CHTbl_::table.

Referenced by replace_tags().

int chtbl_find const CHTbl   htab,
void **    donnee
 

Cover the entire hash table in search for an given element.

Parameters:
htab Pointer to a hash table structure.
donnee Pointer to a user defined data. This pointer will be used:
  • To specify the data to search for.
  • To point to the element's data (that has been found).
Returns:
If the element was in the hash table, that the function returns 0 and donnee points to the element's data. Otherwise, the function return -1.
Warning:
This function lookup compare each element in the hash table with a given element (donnee). It may take long ... do not use it if you don't have to!
Examples:
test_hash_table.c.

Definition at line 255 of file chtbl.c.

References CHTbl_::conteneurs, CHTbl_::corresp, list_data, list_head, list_next, and CHTbl_::table.

int chtbl_init CHTbl   htab,
int    conteneurs,
int(*    h)(const void *cle),
int(*    corresp)(const void *cle1, const void *cle2),
void(*    detruire)(void *donnee)
 

Initialize the hash table. This function must be called first.

Parameters:
htab Pointer to a hash table data structure.
conteneurs Number of linked list in the hash table.
h Pointer to the function used to hash the input key.
corresp Pointer to the function used to compare user's defined data. This function is specific to the type of data stored into the hash table. This function must return if the user defined data are identical, 0 otherwise.
detruire Pointer to the function used to free all allocated memory for the user's defined data. This function is specific to the type of data stored into the hash table.
Returns:
Upon successful completion the function returns 0, otherwise the function returns 1.
Examples:
test_hash_table.c.

Definition at line 23 of file chtbl.c.

References CHTbl_::conteneurs, CHTbl_::corresp, CHTbl_::detruire, CHTbl_::h, list_init(), CHTbl_::table, and CHTbl_::taille.

Referenced by replace_tags().

int chtbl_insert CHTbl   htab,
const void *    donnee
 

Insert data into the hash table.

Parameters:
htab Pointer to the hash table data structure.
donnee Pointer to the user defined data to insert.
Returns:
The function may return one of the following value:
  • 0: The data was not in the hash table and it has been successfuly inserted.
  • 1: The data already was in the hash table (this is not an error).
  • -1: An error occured (this means that the program is running out of memory).
Warning:
Data are NOT copied into the hash table. The hash table only contains pointers to user's data. Therefore you should not free the memory allocated fot the data yourself.
Examples:
test_hash_table.c.

Definition at line 108 of file chtbl.c.

References chtbl_lookup(), CHTbl_::conteneurs, CHTbl_::h, list_ins_next(), CHTbl_::table, and CHTbl_::taille.

Referenced by replace_tags().

int chtbl_lookup const CHTbl   htab,
void **    donnee
 

Searh the hash table for a given data.

Parameters:
htab Pointer to a hash table structure.
donnee Pointer to a user defined data. This pointer will be used:
  • To specify the data to search for.
  • To point to the element's data (that has been found).
Returns:
If the element was in the hash table, that the function returns 0 and donnee points to the element's data. Otherwise, the function return -1.
Examples:
test_hash_table.c.

Definition at line 203 of file chtbl.c.

References CHTbl_::conteneurs, CHTbl_::corresp, CHTbl_::h, list_data, list_head, list_next, and CHTbl_::table.

Referenced by chtbl_insert(), and replace_tags().

void* chtbl_next CHTbl   htab,
int    rewind
 

Returns the next element of a given linked list.

Parameters:
htab Pointer to a hash table structure.
rewind Flag used to set the hash pointer to the first element of the hash. The value of this parameter can be:
  • REWIND_HASH: Set the hash pointer to the first element of the hash.
  • CURRENT_HASH: Set the hash pointer to the current element in the hash.
Returns:
The function returns a pointer to the current element in the hash, or NULL if the current element is the last one.
Warning:
Each time you call the function, it returns the next element in the hash (until the last one where the function returns NULL).
  • When you start walking through a hash table, you must set the parameter rewind to the value REWIND_HASH !. If you don't do that, the baheviour of the function is unpredictable. You may generate a segmentation fault.
  • Do NOT modify (add or remove elements) the hash while you are walking through it! If you don't do that, the baheviour of the function is unpredictable. You may generate a segmentation fault.

Definition at line 310 of file chtbl.c.

References CHTbl_::conteneurs, list_data, list_head, list_next, CHTbl_::pointer, REWIND_HASH, and CHTbl_::table.

int chtbl_remove CHTbl   htab,
void **    donnee
 

Remove a record from the hash table.

Parameters:
htab Pointer to a hash table data structure.
donnee Pointer to a data structure pointer that will point to the data of the element that have been removed. Keep in mind that the user data is NOT freed by the function chtbl_remove(). You must free it yourself.
Returns:
Upon successful completion the function returns 0, otherwise the function returns -1. Please note that the return value -1 is not really an error. It really means that the data was not found in the hash table.
Warning:
You must keep in mind that the data section of the removed element is NOT freed by the function. A pointer to the data section is returned (via donnee). This allows you to free it yourself.
Examples:
test_hash_table.c.

Definition at line 150 of file chtbl.c.

References CHTbl_::conteneurs, CHTbl_::h, list_find(), list_rem_next(), CHTbl_::table, and CHTbl_::taille.


Generated on Thu Apr 3 16:23:44 2003 for Common_C_libraries by doxygen1.3-rc1