A string map object is an array of key-value pairs. A key is an unique string that is used to access the associated value. A value is a string that is associated with the key. Unlike a simple array, a string map is optimized to quickly find an item, even if there are 1000000 items. A string map, for example, can be used to store dictionary data in memory, where keys are words of language A, and values are words of language B. Also can be used to store a list of unique strings that are not necessary associated with values.
To create a string map object, use function CreateStringMap. To work with it, use IStringMap interface.
Example:
IStringMap m=CreateStringMap(0) lpstr s= key1 value1 key2 value2 key3 value3 m.AddList(s) lpstr v=m.Get("key2") if(v) out v else out "not found"
interface# IStringMap :IUnknown Add($k $v) AddList($s $sep) $Get($k) $Get2($k str*v) Set($k $v) Rename($k $newname) Remove($k) RemoveAll() #Count() GetAll(ARRAY(str)*ak ARRAY(str)*av) #GetAllOf($k ARRAY(str)*av) GetList(str*s $sep) EnumBegin() #EnumNext(str*k str*v) EnumEnd() IntAdd($k v) #IntGet($k *v) IntSet($k v) {3426CF3C-F7C1-4322-A292-463DB8729B53} dll "qm.exe" IStringMap'CreateStringMap flags ;;flags: 1 case insens., 2 exists - do nothing, 4 exists - replace, 8 exists - add new, 16 exists - compare
CreateStringMap - creates a map object and returns IStringMap interface pointer. Since it is a COM object, it is destroyed automatically when goes out of scope. Use flags to change the default behavior of other functions. It can be 0 or a combination of values listed below.
1 - case insensitive.
2, 4, 8, 16 - tell what to do when Add, AddList or Rename tries to add a key that already exists. By default, generates error. Other options are listed below. Evaluation order: 16, 8, 4, 2.
2 - do nothing.
4 - replace old value (like Set).
8 - add new item. That is, the map can have multiple identical keys. By default, functions Get, Get2, Set, Rename and Remove will get first added key; functions GetAll, GetAllOf and EnumNext will retrieve identical keys in FIFO order. If flag 4 also is used - last added key, LIFO order.
16 - compare new and old value. If equal, do nothing. If different, see other flags.
Add - adds item (key-value pair) to the map. Error if the key already exists, unless flags 2-16 were used with CreateStringMap. v may be empty ("" or 0). If v is 0, is added "" instead.
AddList - adds multiple items to the map. Error if a key from the list already exists in the map, unless flags 2-16 were used with CreateStringMap. In the list, each line should contain a key-value pair. To separate key and value, use characters specified in sep. If sep is "", use spaces or tabs. Note that sep is not a separator string, but rather a set of characters that can be used. If a line is empty or begins with a separator character, it is not added. If a line contains only key, value is "". If you want to add simple list of strings (keys without values), you can use "[]" as sep to avoid breaking strings into keys and values.
Get - returns the value associated with the specified key. If the key does not exist, returns 0, and also sets _hresult to 1. Warning: the returned value is a lpstr that points to internal data, and therefore becomes invalid after you call a function that modifies the map. To avoid this, assign it to a str variable. Also, this function is not thread-safe, because another thread may call a function that modifies the map. This function is always safe if it is used just to check if the key exists (if(m.Get("key")) ...). Note: if the key exists but the value is empty (added "" or 0), this function returns "", which evaluates to true with if.
Get2 - same as Get, but is always safe. Stores the value into the str variable v. Although this function is slightly slower than Get, use it if the map object can be modified by other threads.
Set - changes value. Error if the key does not exist.
Rename - changes key name. Error if the key does not exist.
Remove - removes item (key and value). If the key does not exist, does not generate an error, but sets _hresult to 1.
RemoveAll - removes all items.
Count - returns the number of items.
GetAll - retrieves all keys and/or values. Stores keys into str array ak, unless it is 0. Stores values into str array av, unless it is 0. Example:
ARRAY(str) ak av m.GetAll(ak av) int i for(i 0 ak.len) out "%s %s" ak[i] av[i]
GetAllOf - retrieves values of all keys that math k. Stores values into str array av, unless it is 0. Returns the number of matching keys. If a matching key does not exist, returns 0, and also sets _hresult to 1. This function is useful if the map is created with flag 8, which allows to add duplicate keys.
GetList - writes all items to a str variable. Each line will contain a key-value pair. Key and value will be separated by sep.
EnumBegin - must be called to begin enumerating items.
EnumNext - retrieves next item. Returns 1 if successful, or 0 if there are no more items. Stores key into str variable sk, unless it is 0. Stores value into str variable sv, unless it is 0. Example:
str sk sv m.EnumBegin rep if(!m.EnumNext(sk sv)) break out "%s %s" sk sv
EnumEnd - should be called (although not necessary) if the enumeration loop exits before all items are enumerated.
IntAdd - adds item. Same as Add, but v is integer number. Internally it is stored as string. To add a numeric value (including double and other types), also can be used Add, but you have to convert it to string (assign it to a str variable and pass the variable to Add). This function just simplifies that.
IntGet - gets value as integer number. If key exists, stores value into v and returns 1, else returns 0. To retrieve a numeric value also can be used other functions (Get, GetAll, etc). These functions return the number as string, and you can use val to convert it to number. This function just simplifies that.
IntSet - changes value. Same as Set, but v is integer number.
To retrieve all items, can be used GetAll, GetList or EnumX functions. GetAll is slower and requires much memory to store all data, especially if the map is large. However, EnumX functions should not be called simultaneously in multiple threads. Items always are retrieved sorted.
All IStringMap functions are thread-safe, except in cases mentioned above. It means that a map object can be used by multiple threads simultaneously.
If a function generates an error, its description always is "The parameter is incorrect". The most common error is when you try to add an item that already exists. To avoid it, you can use Get to check if it exists, or use err (faster), or use flags 2-16 with CreateStringMap. Examples:
if(!m.Get("key2")) m.Add("key2" "new value") else out "already exists" m.Add("key2" "new value") err out "already exists"