TutHashDestroy

Name

TutHashDestroy — deallocate the memory used by a hash table and destroy the table

Synopsis

void TutHashDestroy(table, destroy_func, destroy_arg) 
T_HASH_TABLE table; 
T_HASH_DESTROY_FUNC destroy_func; 
T_PTR destroy_arg; 

Arguments

table — hash table to be destroyed

destroy_func — user-defined function that gets called for every entry in the table (or NULL to signify no user-defined deallocation is necessary)

destroy_arg — the argument that gets passed to destroy_func

Return Values

None

Diagnostics

None

Description

TutHashDestroy destroys a hash table. This procedure deallocates all the table structures created by the call to TutHashCreate and the related functions. It is up to you to deallocate the space occupied by the entries stored in the table and their keys. The deallocation of the entries can be accomplished either by repetitive calls to TutHashDelete for every entry that was inserted into the table, or by specifying the destroy function that gets called for every entry still in the table before the actual table deletion. The destroy function is used to deallocate the space occupied by the keys and entries that were inserted into the table.

This function should be defined as void and have three arguments. All the arguments should be of type T_PTR. The first argument is the key to the entry, the second is the entry itself, and the third is the argument that was passed to TutHashDestroy. Inside the function, void pointers can be recast to the appropriate types to perform the deallocation correctly.

Caution

Always provide the destroy function, because it is the best and safest way to deallocate the memory occupied by hash table entries and their keys.

See Also

TutHashCreate

Examples

This example destroys a hash table with TutHashDestroy:

#define NUM_ITEMS 50 
typedef struct mods MODS; 
struct mods { 
  T_STRING name; 
  T_INT4 number; 
}; 
 
T_HASH_TABLE mod_table; 
 
void destroy_mods(key, mod_rec, arg) 
T_PTR key; 
T_PTR mod_rec; 
T_PTR arg; 
{ 
  MODS modrec = mod_rec;  
  TutOut("Freeing memory for record number %d.", modrec->number); 
  T_FREE(mod_rec); 
} /* destroy_mods */ 
 
int main() 
{ 
  T_INT4 i; 
  MODS *mod_rec; 
 
  /* create the hash table with NUM_ITEMS entries and string keys */ 
  mod_table = TutHashCreateStri(NUM_ITEMS); 
 
  /* fill the table with data */ 
  for (i = 0; i < NUM_ITEMS; i++) { 
    /* allocate the memory for the data */ 
    T_MALLOC(mod_rec, sizeof(MODS), MODS *); 
 
    mod_rec->number = i; 
    sprintf(mod_rec->name, "Item_number_%d", i); 
 
    /* insert the record into the table */ 
    TutHashInsert(mod_table, mod_rec->name, (T_PTR)mod_rec); 
  }  
 
  /* Perform the necessary processing */ 
  ... 
 
  /* destroy the hash table and deallocate the memory */ 
  TutHashDestroy(mod_table, destroy_mods, NULL); 
} /* main */