TutHashTraverse

Name

TutHashTraverse — traverse all entries in a hash table

Synopsis

T_PTR TutHashTraverse(table, traverse_func, traverse_arg) 
T_HASH_TABLE table; 
T_HASH_TRAV_FUNC traverse_func; 
T_PTR traverse_arg; 

Arguments

table — hash table to traverse

traverse_func — function to call once for each entry in the table

traverse_arg — argument to pass to traverse_func

Return Values

The first non-null return value from traverse_func, or NULL if traverse_func always returns NULL.

Diagnostics

If TutHashTraverse fails or traverses all entries in the table, it returns NULL and sets the global SmartSockets error number to one of:

Description

TutHashTraverse traverses all entries in a hash table and calls traverse_func once for each entry. The traverse_func function is called with three arguments: the key, the value, and the traverse_arg that TutHashTraverse was called with. When traverse_func returns a non-null value, then TutHashTraverse returns with that value.

There are two common uses for TutHashTraverse: to perform an operation on each entry and to search for a particular entry. In the first case, write traverse_func to always return NULL. In the second case, traverse_func should return NULL until it finds the desired entry, and then return some kind of non-null value (such as the entry value).

Caution

Be careful to always return a value from traverse_func. The order that the entries are traversed is indeterminate. Do not add or delete entries from the hash table during the traversal.

See Also

TutHashDump, TutHashLookup

Examples

This example is a traversal function that prints the values of key, value, and arg:

T_PTR print_info(key, value, arg) 
T_PTR key; 
T_PTR value; 
T_PTR arg; 
{ 
  TutOut("key = %x, value = %x, arg = %x\n", key, value, arg); 
  return NULL; /* continue traversal */ 
} /* print_info */ 

To call this function, this code could be used:

TutHashTraverse(table, print_info, NULL);