defineMap()

Synopsis

Defines a new "map". The map lasts for the duration of the Intent session. A "map" data structure is sometimes referred to as a "hash table" or "lookup table". If you define another map with the same name, the reset? argument specifies whether the existing map is cleared. This function always returns True.

You must invoke defineMap() prior to attempting to store or retrieve data from it. This may be a good reason to use an onCreate rule.

Syntax

defineMap ( mapName As Name, _
            Optional reset? As Boolean = True ) As Boolean 

Argument	Type	Description
mapName	Name	The name of the map
reset?	Boolean	Optional; if True (default) and a map with the same name exists, the data in the map is cleared at that point. If False, nothing happens to the existing data in the map.

Example 1

Initial definition

Intent >defineMap(:myMap) 
--> True 

Defines a map named 'myMap'.

Example 2

Redefinition (reset? is True by default)

Intent >defineMap(:myMap) 
--> True 

This redefines the map defined in Example 1, clearing any values that may have been previously set using setMapValue().

Example 3

Redefinition without resetting

Intent >defineMap(:myMap, reset? := False) 
--> True 

This attempts to define a map named 'myMap'. But since a map with this name exists and reset? is False, the existing map is left alone.

Example 4

This example defines a map, sets a couple values, defines the map again without resetting it, gets map keys and some values, and finally deletes a map value.

Intent >defineMap(:myMap)
--> True
Intent >setMapValue(:myMap, :myStringValue, "A String")
--> True
Intent >setMapValue(:myMap, :myIntegerValue, 123)
--> True
Intent >defineMap(:myMap, reset? := False)
--> True
Intent >getMapKeys(:myMap)
--> {:myStringValue, :myIntegerValue}
Intent >getMapValue(:myMap, :myStringValue)
--> "A String"
Intent >getMapValue(:noMap, :noValue)
--> NoValue
Intent >deleteMapValue(:myMap, :myIntegerValue)
--> True
Intent >getMapValue(:myMap, :myIntegerValue)
--> NoValue