HashTableIteratorCreate
int HashTableIteratorCreate (HashTableType table, HashTableIterator *iterator);
Purpose
Begins iterating through the key-value pairs in a hash table. The function returns an iterator you can pass to HashTableIteratorGetItem and HashTableIteratorAdvance.
If the table is empty, the iterator references the end of the list, and the function returns HASH_TABLE_END.
An iterator traverses all the key-value pairs stored in the hash table. The iterator is like a pointer with two primary operations: referencing a given key-value pair in the hash table and modifying itself to point to the next key-value pair.
When you are done iterating, you must free the iterator by calling HashTableIteratorDispose on the iterator.
Example Code
{
int status = 0;
HashTableType table;
HashTableIterator iter;
int key, value;
/* ... */
for (status = HashTableIteratorCreate(table, &iter);
status >= 0 && status != HASH_TABLE_END;
status = HashTableIteratorAdvance(table, iter))
{
status = HashTableIteratorGetItem(table, iter, &key, sizeof(int), &value, sizeof(int));
/* do something with key and value */
}
HashTableIteratorDispose(table, iter);
}
 |
Note It is safe to nest iteration loops, as long as you create a new iterator for each loop. |
Parameters
| Input | ||
| Name | Type | Description |
| table | HashTableType | Hash table through which to iterate. |
| Output | ||
| Name | Type | Description |
| iterator | HashTableIterator |
A reference to a HashTableIterator variable in which to store the created iterator. The iterator begins at the first key-value pair in the table. If the table is empty, the iterator references the end of the list, and the function returns HASH_TABLE_END. |
Return Value
| Name | Type | Description |
| status | int |
Returns a value indicating if the function was successful.
A negative number means an error occurred. If the hash table is empty, the iterator references the end of the list, and the function returns HASH_TABLE_END. For a detailed error message, pass the returned value to GetGeneralErrorString. |
Additional Information
Library: Programmer's Toolbox
Include file: toolbox\toolbox.h
LabWindows/CVI compatibility: LabWindows/CVI 8.5 and later
Example
Refer to toolbox\hashtable.cws for an example of using the HashTableIteratorCreate function.