Mapping (associative arrays)

Mappings save arbitrary key/value pairs. The keys and values are saved in two arrays (one for keys and one for values). A mapping with key:value pairs "one": 1, "two":2, "three":3 looks internal as follows:

key value
"one" 1
"two" 2
"three" 3

The values for the keys are searched via the keys. The keys can be of the following types string, char, int, uint/unsigend, float, bit32, bit64, long, ulong, time, atime. The following types cannot be used for keys: no Arrays (dyns and dyn_dyn_*), no bool, mapping, anytype, function_ptr, class, enum, ... . If you want to find the value for the key "one" the position of the key "one" is searched in the key array and the value at this position in the value array is returned.

A comparison between two mappings is only performed as binary comparison!

Important: You must not rely on the internal order of the keys in a mapping. Mappings represent an unordered set of key/value pairs.

Example

Following example shows how to create a mapping like in the description above and how to address a specific value.

main()
{
   mapping m;
   m["one"] = 1;
   m["two"] = 2;
   m["three"] = 3;
   DebugN(m["one"]); //Output: 1
}
Note: An element inside a mapping can be addressed with the dot notation when the key is a string and follows the naming convention for Control variables

You can also use a mapping or a dyn_string inside a mapping.

Note:

A mapping is a hash table, which is not optimal when iterating via integer index position.

A mapping is very fast when the index used is really the KEY used for a key/value pair.

If it is important to be fast by addressing via the KEY, use a mapping.

If it is important to be fast by addressing via int index, use a vector or dyn_X.

If both cases are important, it is possible to store the value via a shared_ptr in two different containers: mapping AND vector.

Example

Following example shows how to use a mapping and a dyn_string inside a mapping.

{
   mapping root;
   mapping child_map;
   dyn_string child_dyn;
   child_map["one"] = 1;
   child_map["two"] = 2;
   child_map["three"] = 3;
   child_dyn[1] = "one";
   child_dyn[2] = "two";
   child_dyn[3] = "three";
   root["c1"] = child_map;
   root["c2"] = child_dyn;
   DebugN("root =>child1 =>element2:" + root["c1"]["two"]); //Output: 2
   DebugN("root =>child2 =>element1:" + root["c2"][1]); //Output: one
}

Advantages and Disadvantages of mapping compared to dyn_string

Advantages

  • It is possible to use other values than int as index

  • Needs less memory space since the indices are scattered

Disadvantages

  • slower reading and writing times

  • needs more memory space

CAUTION: The performance of a mapping is significantly slower when non-supported types are assigned as key without explicit typecast.

Mapping functions

mappingClear() mappingGetKey() mappingGetValue()
mappingHasKey() mappingKeys()
mappingRemove() mappinglen()

Examples for Mapping Functions

Example 1

Access to the mapping via key.


  int i; mapping m; m["one"] = 1; //sets the value to 1
  m["two"] = 2; //sets the value to 2
  DebugN("The value of m[one]is = " + m["one"], "the value should be = 1");
  DebugN("The value of m[two]is = " + m["two"], "the value should be = 2");
  i = m["one"]; //sets i to the value of "one"
  DebugN("i is =" + i, "i should be = 1");

Elements of a mapping can also be addressed by using the dot notation, e.g. m.one = 42;

Example 2

Output of the entry count of the mapping using mappinglen().


  DebugN("mappinglen is" + mappinglen(m), "should be = 2");

Example 3

Output of all key values of the mapping using mappingKeys().


  DebugN("mappingKeys are=" + mappingKeys(m), "should be one and two as string");

Example 4

Output of the key value on a specific index in the mapping using mappingGetKey().


  for(int i = 1; i <= mappinglen(m); i++) DebugN("mappingGetKey", i, "is =" + mappingGetKey(m,i));

Example 5

Output of the value on a specific index in the mapping using mappingGetValue().

  for(int i = 1; i <= mappinglen(m); i++) DebugN("mappingGetValue", i, "is =" + mappingGetValue(m,i));

Example 6

Check if mapping has key using mappingHasKey().


  DebugN("mappingHasKey one", "is =" + mappingHasKey(m,"one"),"should be = TRUE");

Example 7

Removing an entry using mappingRemove().


  DebugN("mappingRemove: one", "is =" + mappingRemove(m, "one"), "should be = 0");

dyn_mapping

dyn_mapping is a dynamic list of mappings.

Example

The function getGroupsOfUserPVSS() returns a list of mappings (= a dyn_mapping) with the group information of the selected user. The user "demo" is only located in the user group guest, so only the mapping for this group is contained inside the returning dyn_mapping.

main()
{
   dyn_mapping m;
   m = getGroupsOfUserPVSS(4098);
   DebugN("Groups of the user demo", m);
}