Using Linked Lists, Maps, and Dictionaries
The twList functions provide a set of utility features that you can use to perform the following tasks:
• Create / delete a linked list.
• Add a new entry to an existing linked list.
• Remove an existing entry from a linked list.
• Clear all entries from a linked list.
• Iterate over the entries in a linked list.
The twList.h file defines functions that support these activities. What is important to note is that when you want to iterate over a list, you should now use the twList_ForEach() function instead of twList_Next(), which is deprecated as of release 1.3.3 of the C SDK. The twList_ForEach() function provides a way to iterate over a specified list quickly and in a thread-safe manner. Further, it allows you to iterate over different kinds of structures, namely lists, maps, and dictionaries. It first determines whether the list passed in is a list or not and checks if list->count == 0. If these conditions are true, it exits. If it is a list, it locks the list, defines a node as the first entry in the list, and then iterates over the list, using the listHandler.
For more details about these functions, refer to the source files and/or the generated documentation that accompanies the C SDK. The generated documentation is located in the /documentation subdirectory of the C SDK installation.
Maps
The twMap.h and twMap.c files provide functions and mock list interfaces to perform the following tasks on a hashmap:
• Create a hashmap.
• Add a new element to a hashmap.
• Retrieve an existing element from a hashmap.
• Search for an element in a hashmap.
• Remove an existing element from a hashmap.
• Remove all elements from a hashmap.
• Free the memory associated with a hashmap.
• Delete a hashmap.
• Determine the current size of a hashmap.
• Iterate over the elements in a map.
• Replace the value of an element in a map.
For more details about these functions, refer to the source files and/or the generated documentation that accompanies the C SDK. The generated documentation is located in the /documentation subdirectory of the C SDK installation.
Dictionaries
The twDict is an abstraction that lets you treat lists and maps the same way. A twDict can be implemented with either a map or a list. Lists use less memory and are faster at inserting new items. Lists are slow for finding an item. Maps are slower to insert new items, but are much faster at finding items. Maps do use more memory. By providing the twDict abstraction, you can decide if you want a low memory implementation (list) to run in a smaller memory footprint or a higher performing implementation that will require more memory. This can be set at compile time with twDictionaryMode tw_dictionary_mode=TW_DICTIONARY_MODE, in twDict.c before compiling.
 |
This has not been tested in any mode other than TW_DICTIONARY_MODE as of version 1.4.0 of the C SDK.
|
For more information about twDict, refer to the source files and/or the generated documentation that accompanies the C SDK. The generated documentation is located in the /doc subdirectory of the C SDK installation.
Here is a snippet that creates a dictionary called list_Foreach, containing three items. It uses the twMap_forEach to iterate over the dictionary.
list_Foreach = twDict_Create(NULL, NULL);
twDict_Add(list_Foreach,(void*)"A");
twDict_Add(list_Foreach,(void*)"B");
twDict_Add(list_Foreach,(void*)"C");
twDict_Foreach(list_Foreach, twDict_ForEach_ForEachHandler, (void *) userData);}
twDict_Add(list_Foreach,(void*)"A");
twDict_Add(list_Foreach,(void*)"B");
twDict_Add(list_Foreach,(void*)"C");
twDict_Foreach(list_Foreach, twDict_ForEach_ForEachHandler, (void *) userData);}
 |
It is recommended to use twDict instead of tw_List. Further, twList_Next() is deprecated; instead use the new Foreach iterator to process entries in a list or dictionary. The Foreach iterator significantly improves performance.
|