MAP

MAPs or associative arrays (also known as 'mappings' or 'hashes') are arrays which use a TEXT value as an index, as opposed to regular arrays which use a NUMBER as index.

Associative arrays are an extension to the regular arrays, because they allow any text to be used as an index and thus have no fixed size. This allows you to use complex information (such as social security numbers, policy numbers, car license numbers etcetera) as index entries.

MAPs need to be declared before they can be used:

MAP TYPE name_of_the_map

Rules:

• TYPE can be BOOL, NUMBER or TEXT. This determines what kind of data can be stored in the MAP.
• The name of the MAP must start with a lower-case character and be limited to lower-case characters, digits and underscores. Spaces are not allowed.
• The name must be unique in the scope where it is declared.
• The MAP must be declared before it can be used.
• A MAP can be used everywhere a regular array can be used.

The number of elements in a MAP is only limited by the amount of (virtual) memory available on the machine running the ITP Model.

Use

After a map has been declared it can be used everywhere a regular array can be used.

Notes:

• The default value of an element in the MAP is an empty text (TEXT), 0 (NUMBER) or FALSE (BOOL).
• If a model tries to retrieve an element that is not present in the MAP, ITP will return the default value for that element.
• The ASSIGN statement must be used to add an element to a MAP or to assign a value to an element.
• The indices in a MAP are limited to the character set Latin-1. Any characters outside this set are silently discarded.
  Enabling the setting EnhancedUnicodeMaps in ITP/Server allows the use of any Unicode character in the indices.

Note

Elements are auto created whenever they are accessed. This means that you cannot test for the presence of an element by accessing it. To test for the presence of an element with a known key or index value you must use the functions as presented below.

Example 1

Obtaining the value of a MAP element:

ASSIGN variable_name := map_name[ "key" ] 

The value of the element with index "key" is assigned to the variable variable_name.

Example 2

Adding an element and assigning a value to that element in a MAP:

ASSIGN map_name [ "text_expression" ] := value_expression

The map element with index "text_expression" will now contain the value value_expression.

Example 3

Declaring a MAP as parameter of a procedure or function:

FUNC TEXT example_func ( MAP TEXT map_name )

Example 4

Passing a MAP to a procedure or function:

APROC example_proc ( map_name )

Example 5

Using a MAP as a VALUES list in an INTERACT:

INTERACT "Test"
	QUESTION "Question"
	VALUES ( map_name )
	ANSWER variable

Values in TEXT MAP

You can assign values of a TEXT MAP and a FIELDSET to each other, or merge them. Refer to the topic FIELDSET for more information.