TutHashSort

Name

TutHashSort — return an array of sorted values from a hash table

Synopsis

T_PTR TutHashSort(table, array_size_return, cmp_func, select_func) 
T_HASH_TABLE table; 
T_INT4 *array_size_return; 
T_HASH_SORT_CMP_FUNC cmp_func; 
T_HASH_SORT_SELECT_FUNC select_func; 

Arguments

table — hash table to be searched for entries.

array_size_return — pointer to integer where TutHashSort stores the number of values in the list after the sort.

cmp_func — user-defined function used to compare keys while sorting. If NULL is specified, the default function strcmp is used to compare keys.

select_func — user-defined function used to qualify keys for the sort. If NULL is specified, all entries in the table are sorted.

Return Values

Array of sorted values in the table, selected according to the criteria imposed by select_func.

Diagnostics

None

Description

TutHashSort returns a sorted array of values from the table. The entries are selected based on the criteria provided in select_func. If select_func is NULL, all entries in the hash table are sorted and returned. For comparison, a user-defined comparison function is used. If cmp_func is NULL, strcmp is used to compare the entries. Using different combinations of select and comparison functions produces lists of entries sorted in different order and selected according to various criteria. Note that the sort in no way affects the order in which entries are stored in the hash table.

cmp_func takes as arguments two T_PTR keys to entries in the table. The first argument holds a key to an already sorted entry. The second argument is the key to the current entry. If the default comparison function strcmp is used, the returned list is sorted in the ascending order. The comparison function should have return values equivalent to that of the strcmp function.

select_func takes as arguments the T_PTR key and value for the entry into the hash table. It returns TRUE if the entry satisfies the selection criteria, otherwise it returns FALSE.

The return value from TutHashSort is a dynamically allocated array of T_PTR-sized hash table entries. The return value is of type T_PTR instead of T_PTR * so that no cast is needed by the calling function.

Caution

TutHashSort allocates the space for the sorted array of entries. It is up to you to free that memory.

If TutHashSort does not select any entries from the table, it returns NULL.

See Also

None

Examples

This example returns a sorted array of hash table entries:

T_HASH_TABLE table; 
T_PTR *values; /* each pointer really contains an integer value */ 
T_INT4 counter; 
T_INT4 num_values; 
 
/* create a hash table and put 4 integer values in it */ 
table = TutHashCreateStr(4); 
TutHashInsert(table, "EAST", (T_PTR)90); 
TutHashInsert(table, "SOUTH", (T_PTR)180); 
TutHashInsert(table, "WEST", (T_PTR)270); 
TutHashInsert(table, "NORTH", (T_PTR)360); 
 
/* sort the table and print the values */ 
values = TutHashSort(table, &num_values, NULL, NULL); 
TutOut("Sorted %d entries.\n", num_values); 
for (counter = 0; counter < num_values; counter++) { 
  TutOut("Value[%d] = %d\n", counter, (int)values[counter]); 
} 
T_FREE(values);