Associations

An association (also referred to as a dictionary) links a value to a key. Both of these can have any data type. The data type identifier for an association is Map.

In some ways, associations are similar to fields. The indexes in a field can be seen as the keys, through which the saved values are accessed:

1 Map m1 = CreateMap();
2 m1[0] = "First"
3 m1[1] = "Second";
4 m1[2] = "Third";

The above example uses integers as keys (the values 0, 1 and 2). However – unlike fields – an association can also use any other data type as keys. In the following example, strings are used:

1 Map m2 = CreateMap();
2 m2["Personnel No."] = 123456;
3 m2["First Name"] = "John";
4 m2["Surname"] = "Doe";
5
6 Trace(TRACELEVEL_INFO, m2);

The output looks as follows:

[[Personnel No., 123456], [First Name, John], [Surname, Doe]]

This shows a further difference between associations and fields: A field only stores the values because the indexes are already provided by the field elements and they are always the same. Associations do not have indexes in the sense that Elements are accessed by way of a position. Instead, they have a key that can be used independently of the actual physical position. A value is always associated with a key, not with a physical position.

As the preceding examples show, a mapped key is automatically added to the dictionary if it doesn't yet exist there. If the key already exists, its existing value is replaced by the new value.

Unlike a field, an association cannot be initialized with the syntax

array a = ["A", "B", "C"];

If an association is to be filled with concrete values at its definition, the function CreateMap() must be called with an initialization field as the argument:

1 Map m3 = CreateMap([
2        ["Test-1", TRUE],
3        ["Test-2", FALSE],
4        ["Test-3", TRUE]
5        ]);
6
7 Trace(TRACELEVEL_INFO, m3);

The output looks as follows:

[[Test-1, True], [Test-2, False], [Test-3, True]]

The field with the initialization values must map the key-value relationships as a matrix. It is therefore a two-dimensional field whose second dimension always consists of two elements: the key followed by the value. Any number of key-value relationships can be specified at initialization.