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!

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


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

   mapping m;
   m["one"] = 1;
   m["two"] = 2;
   m["three"] = 3;
   DebugN(m["one"]); //Output: 1

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


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

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

  • Needs less memory space since the indices are scattered

  • slower reading and writing times

  • needs more memory space

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

Mapping functions

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. = 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 is a dynamic list of mappings.


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.

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