Clara-Doc - Programmer Reference
Module: CTMAPX
Methods
| Method | Description |
| CTMAPX_BInsert | Inserts an item in the map from a CTBUFF instance. |
| CTMAPX_BIterNext | Retrieves the next map item in keyed order within an iteration loop into a CTBUFF instance. |
| CTMAPX_BLookup | Retrieves an item from the map into a CTBUFF instance. |
| CTMAPX_Clear | Removes all items from the map. |
| CTMAPX_Constructor | Creates a CTMAPX instance. |
| CTMAPX_Destructor | Releases the resources allocated by the map and releases the map itself. |
| CTMAPX_Insert | Inserts an item in the map. |
| CTMAPX_ItemSize | Returns the size of a map item from a specified key value. |
| CTMAPX_IterNext | Moves the current item pointer to the next available item in keyed order within an iteration loop. |
| CTMAPX_IterNextSize | Returns the size of the next available item within an iteration loop. |
| CTMAPX_IterStart | Begins an iteration loop. |
| CTMAPX_Lookup | Retrieves an item from the map. |
| CTMAPX_Remove | Removes an item from the map. |
Description
Introduction
The CTMAPX class implements a hash map. A hash map is a collection of objects where each object is identified by a key. By specifying a key value, the hash map will return the associated item.
The CTMAPX class is implemented with an AVL tree, which is a self-balancing search tree algorithm. you can see visually how an AVL tree works here
In the CTMAPX implementation, items can have a size up to 16 megabytes; the associated key can also have a size of up to 16 megabytes. Using the CTMAPX class requires one to understand buffer manipulation, memory allocation and memory management. It is not trivial to use a CTMAPX object but it can yield powerful results when properly used.
Creating and disposing of CTMAPX instances
Before using a CTMAPX, a CTMAPX instance has to be created (constructed). This is done by calling the CTMAPX_Constructor method. A pointer to a CTMAPX instance will be returned to the caller. This pointer will be used in calls to other CTMAPX methods. Every time CTMAPX_Constructor is called, a new CTMAPX instance is created and accessible through the pointer that is returned. This allows for several CTMAPX instances within the same porgram. Be sure to pass the appropriate pointer when calling CTMAPX methods. Once a CTMAPX instance is no longer needed, its resources have to be reclaimed via a call the the CTMAPX_Destructor method (you must pass the pointer to the CTMAPX instance that will be garbage collected). Call the CTMAPX_Constructor method on every CTMAPX instance once they are no longer needed. In between calls to the constructor and the destructor for a given CTMAPX instance, you may call any CTMAPX method on that CTMAPX instance.
/INCLUDE QINCSRC,CTBASE
DRc S 10I 0
DpMap S *
/Free
pMap = CTMAPX_Constructor();
// Use CTMAPX instance via methods by using the pMap pointer
//
// ...
// We are done and need to gargabe collect CTMAPX resources
CTMAPX_Destructor(pMap);
*InLR = *On;
Return;
/End-Free
Specifying item keys
Item keys must be specified as NULL-terminated strings so that the CTMAPX class can allow for items to have keys of varying sizes.