Map Object

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.

Table of Contents

Static Methods

Call

Creates a Map and sets items.

MapObj := Map(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.

Methods

Clear

Removes all key-value pairs from a map.

MapObj.Clear()

Clone

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.

Delete

Removes a key-value pair from a map.

MapObj.Delete(Key)
Key

Type: Integer, object or String

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

Returns the removed value.

Get

Returns the value associated with a key, or a default value.

Value := MapObj.Get(Key , Default)

This method does the following:

When Default is omitted, this is equivalent to MapObj[Key], except that __Item is not called.

Has

Returns true if the specified key has an associated value within a map, otherwise false.

MapObj.Has(Key)

Set

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.

Returns the map.

__Enum

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:

Key

Type: Integer, object or String

The key.

Value

The value.

__New

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.

Properties

Count

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

Count := MapObj.Count

Capacity

Retrieves or sets the current capacity of a map.

MapObj.Capacity := MaxItems
MaxItems := MapObj.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 a map's case sensitivity setting.

MapObj.CaseSense := Setting
Setting := MapObj.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.

Default

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. When the script queries a key which is not found, the map checks for this property before 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.

__Item

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

Value := MapObj[Key]
MapObj[Key] := Value
Key

Type: Integer, object or String

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.