Map Examples

Example 1. Creating a map object.

local.vResult = Map.Put("MapName", "Key1", 1);

Map.CreateMap("MapName");

Map.Put("MapName", "Key1", 1);

Map.Put("MapName", "Key2", 2);

Map.Put("MapName", "Key1", 3);

local.vSize = Map.Size("MapName");

Note:

MapName – this is the name of the array object.
"Key1", "Key2" – these are keys to assign values.

The first call will fail, returning result code 11654 as the map does not exist. Subsequent calls, being after the 'CreateMap' method will succeed, and record the values specified. Two keys are used to populate the map, with Key1 assigned first, then overwritten. The resulting map will be [(Key1, 3), (Key2,2)], with size of 2.

Example 2. Retrieving a map element.

local.vKey = "Key"

IF (Map.Contains("MapName", local.vKey))

{

local.vKeyValue = Map.Get("MapName", local.vKey)

}

ELSE

{

Form.MessageBox("Error", "Key not found.", 0)

local.vNotFound = Map.Get("MapName", local.vKey)

}

Note:

"MapName" – this is the name of the map object.
local.vKey – this is a variable holding the key name.
local.vKeyValue – this is the value of the key.
local.vNotFound – this is the value of the lookup, even though key is not in map.

The Map.Contains() method is first used to check if the key specified is contained in the map specified. If it is, the value associated with the key will be retrieved and stored in local.vKeyValue, else an error message box will display. The local.vNotFound value will then be looked up in the map with NULL value returned, as the key does not exist.

Example 3. Removing a key value from a map.

local.vSize = Map.Size("MapName");

Map.Remove("MapName", "Key1");

local.vSize = Map.Size("MapName");

Note:

"MapName" – this is the name of the map object.

Map.Remove() will remove the specified key from the map named. If used after Example 1, the initial size will be 2, and then will be 1 after the Map.Remove() method is called in this example.

Example 4. Clearing, removing a map.

Map.Clear("MapName");

local.vSize = Map.Size("MapName");

Map.RemoveMap("MapName");

local.vSize = Map.Size("MapName");

Note:

"MapName" – this is the name of the map object.

The Map.Clear() method will clear the entire contents of the map, but keep the map name valid in the application. A call to size will return 0. Using the Map.RemoveMap() method, the map may be cleared from memory. The size of a nonexistent map is -1.