A Map object associates or maps one set of values, called keys, to another set of values. A key and the value it is mapped to are known as a key-value pair. A map can contain any number of key-value pairs, but each key must be unique.
A key may be any Integer, object reference or null-terminated String. Comparison of string keys is case-sensitive, while objects are compared by reference/address. Float keys are automatically converted to String.
The simplest use of a map is to retrieve or set a key-value pair via the implicit __Item property, by simply writing the key between brackets following the map object. For example:
clrs := Map() clrs["Red"] := "ff0000" clrs["Green"] := "00ff00" clrs["Blue"] := "0000ff" for clr in Array("Blue", "Green") MsgBox clrs[clr]
The documentation below uses
aMap as a placeholder for any Map object. Note that "map" should not be used as a variable name as it is used to refer to the Map class itself.
Map objects are based on
Map.Prototype, which is based on
Object.Prototype. In addition to the methods and property inherited from Object, Map objects have the following predefined methods and properties:
Removes all key-value pairs from the map.
Returns a shallow copy of the object.
Clone := aMap.Clone()
All key-value pairs are copied to the new map. Object references are copied (like with a normal assignment), not the objects themselves.
Own properties, own methods and base are copied as per Obj.Clone.
Removes a key-value pair from the map.
Returns true if Key has an associated value within the map, otherwise false.
Sets zero or more items.
aMap.Set(Key, Value, Key2, Value2, ...)
Returns the map.
Enumerates key-value pairs.
For Key , Value in aMap
Returns a new enumerator. This method is typically not called directly. Instead, the map object is passed directly to a for-loop, which calls __Enum once and then calls the enumerator once for each iteration of the loop. Each call to the enumerator returns the next key and/or value. The for-loop's variables correspond to the enumerator's parameters, which are:
Retrieves the number of key-value pairs present in the map.
Count := aMap.Count
Retrieves or sets the current capacity of the map.
aMap.Capacity := MaxItems
MaxItems := aMap.Capacity
The maximum number of key-value pairs the map should be able to contain before it must be automatically expanded. If setting a value less than the current number of key-value pairs, that number is used instead, and any unused space is freed.
Retrieves or sets the map's case sensitivity setting.
aMap.CaseSense := Setting
Setting := aMap.CaseSense
One of the following values:
"On": Key lookups are case sensitive. This is the default setting.
"Off": The letters A-Z are considered identical to their lowercase counterparts.
"Locale": Key lookups are case insensitive according to the rules of the current user's locale. For example, most English and Western European locales treat not only the letters A-Z as identical to their lowercase counterparts, but also non-ASCII letters like Ä and Ü as identical to theirs. Locale is 1 to 8 times slower than Off depending on the nature of the strings being compared.
When assigning a value, the strings
"0" can also be used.
Attempting to assign to this property causes an exception to be thrown if the Map is not empty.
Retrieves or sets the value of a key-value pair.
Value := aMap[Key]
aMap[Key] := Value
When retrieving a value, Key must be a unique value previously associated with another value. An exception is thrown if Key has no associated value within the map.
When assigning a value, Key can be any value to associate with Value; in other words, the key used to later access Value. Float keys are automatically converted to String.
The property name __Item is typically omitted, as shown above, but is used when overriding the property.
Creates a Map and sets items.
aMap := Map(Key1, Value1, Key2, Value2, ...)
This is equivalent to creating a map with
aMap := Map.new(), setting its initial Capacity, and then setting each item with
aMap[Key] := Value. Multiple expansions are avoided, but Capacity is not guaranteed to be exact.