class Map extends Object
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]
"MapObj" is used below as a placeholder for any Map object, as "Map" is the class itself.
In addition to the methods and property inherited from Object, Map objects have the following predefined methods and properties.
Creates a Map and sets items.
MapObj := Map(Key1, Value1, Key2, Value2, ...)
MapObj := Map.Call(Key1, Value1, Key2, Value2, ...)
This is equivalent to setting each item with MapObj[Key] := Value, except that __Item is not called and Capacity is automatically adjusted to avoid expanding multiple times during a single call.
Parameters are defined by __New.
Removes all key-value pairs from a map.
MapObj.Clear()
Returns a shallow copy of a map.
Clone := MapObj.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 a map.
RemovedValue := MapObj.Delete(Key)
Type: Integer, Object or String
Any single key. If the map does not contain this key, an UnsetItemError is thrown.
Type: Any
This method returns the removed value.
Returns the value associated with a key, or a default value.
Value := MapObj.Get(Key , Default)
This method does the following:
MapObj.Default, if defined.When Default is omitted, this is equivalent to MapObj[Key], except that __Item is not called.
Returns true if the specified key has an associated value within a map, otherwise false.
MapObj.Has(Key)
Sets zero or more items.
MapObj.Set(Key, Value, Key2, Value2, ...)
This is equivalent to setting each item with MapObj[Key] := Value, except that __Item is not called and Capacity is automatically adjusted to avoid expanding multiple times during a single call.
Type: Object
This method returns the Map.
Enumerates key-value pairs.
For Key , Value in MapObj
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:
Sets items. Equivalent to Set.
MapObj.__New(Key, Value, Key2, Value2, ...)
This method exists to support Call, and is not intended to be called directly. See Construction and Destruction.
Retrieves the number of key-value pairs present in a map.
Count := MapObj.Count
Retrieves or sets the current capacity of a map.
MaxItems := MapObj.Capacity
MapObj.Capacity := MaxItems
MaxItems is an integer representing 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 a map's case sensitivity setting.
CurrentSetting := MapObj.CaseSense
MapObj.CaseSense := NewSetting
CurrentSetting is NewSetting if assigned, otherwise On by default (but note that this property only retrieves the string variant of the current setting).
NewSetting is one of the following strings or integers (boolean):
On or 1 (true): Key lookups are case-sensitive. This is the default setting.
Off or 0 (false): Key lookups are not case-sensitive, i.e. the letters A-Z are considered identical to their lowercase counterparts.
Locale: Key lookups are not case-sensitive 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.
Attempting to assign to this property causes an exception to be thrown if the Map is not empty.
Defines the default value returned when a key is not found.
MapObj.Default := Value
This property actually doesn't exist by default, but can be defined by the script. If defined, its value is returned by __Item or Get if the requested item cannot be found, instead of throwing an UnsetItemError. It can be implemented by any of the normal means, including a dynamic property or meta-function, but determining which key was queried would require overriding __Item or Get instead.
Retrieves or sets the value of a key-value pair.
Value := MapObj[Key]
Value := MapObj.__Item[Key]
MapObj[Key] := Value
MapObj.__Item[Key] := Value
When retrieving a value, Key must be a unique value previously associated with another value. An UnsetItemError is thrown if Key has no associated value within the map, unless a Default property is defined, in which case its value is returned.
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.