Map 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]

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:

Methods:

Properties:

Functions:

Methods

Clear

Removes all key-value pairs from the map.

aMap.Clear()

Clone

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.

Delete

Removes a key-value pair from the map.

aMap.Delete(Key)
Key

Type: Integer, object or String

Any single key. If the map does not contain this key, an exception is thrown.

Return Value

The removed value.

Has

Returns true if Key has an associated value within the map, otherwise false.

aMap.Has(Key)

Set

Sets zero or more items.

aMap.Set(Key, Value, Key2, Value2, ...)

This is equivalent to setting each item with aMap[Key] := Value, except that __Item is not called and Capacity is automatically adjusted to avoid expanding multiple times during a single call.

Returns the map.

__Enum

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:

Key

Type: Integer, object or String

The key.

Value

The value.

Properties

Count

Retrieves the number of key-value pairs present in the map.

Count := aMap.Count

Capacity

Retrieves or sets the current capacity of the map.

aMap.Capacity := MaxItems
MaxItems := aMap.Capacity
MaxItems

Type: Integer

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.

CaseSense

Retrieves or sets the map's case sensitivity setting.

aMap.CaseSense := Setting
Setting := aMap.CaseSense
Setting

Type: String

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 "1" and "0" can also be used.

Attempting to assign to this property causes an exception to be thrown if the Map is not empty.

__Item

Retrieves or sets the value of a key-value pair.

Value := aMap[Key]
aMap[Key] := Value
Key

Type: Integer, object or String

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.

Functions

Map

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.