Map 对象

class Map extends Object

Map(映射) 对象将一组称为 键 的值关联或 映射 到另一组值. 键及其映射到的值称为键-值对. 映射可以包含任意数量的键值对, 但是每个键必须是唯一的.

键可以是任何整数, 对象引用或以 null 结尾的字符串. 字符串键的比较是区分大小写的, 而对象是通过引用/地址进行比较的. 浮点数键被自动转换成字符串.

映射的最简单用法是通过隐式的 __Item 属性检索或设置键-值对, 只需在映射对象后面的方括号中写入键. 例如:

clrs := Map()
clrs["Red"] := "ff0000"
clrs["Green"] := "00ff00"
clrs["Blue"] := "0000ff"
for clr in Array("Blue", "Green")
    MsgBox clrs[clr]

下面使用 "MapObj" 作为任何 Map 对象的占位符, 因为 "Map" 就是类本身.

除了从 Object 继承的方法和属性外, Map 对象还具有以下预定义的方法和属性.

目录

静态方法

Call

创建一个 Map 并设置项目.

MapObj := Map(Key1, Value1, Key2, Value2, ...)
MapObj := Map.Call(Key1, Value1, Key2, Value2, ...)

这等同于使用用 MapObj[Key] := Value 来设置每个项目, 除了 __Item 没有被调用, 而且 Capacity 会被自动调整以避免在一次调用中多次扩展.

参数由 __New 定义.

方法

Clear

从映射中删除所有键-值对.

MapObj.Clear()

Clone

返回对象的一个浅拷贝.

Clone := MapObj.Clone()

所有键-值对都被复制到新映射. 对象 引用 被复制(就像普通的赋值一样), 而不是对象本身.

根据 Obj.Clone 来复制自有的属性, 方法和基.

Delete

从映射中删除键-值对.

RemovedValue := MapObj.Delete(Key)

参数

Key

类型: 整数, 对象或字符串

任意一个键. 如果映射不包含此键, 则抛出 UnsetItemError.

返回值

类型: Any

此方法返回删除的值.

Get

返回键关联的值, 或者一个默认值.

Value := MapObj.Get(Key , Default)

此方法执行以下操作:

当 Default 被省略时, 这等同于 MapObj[Key], 除了没有调用 __Item.

Has

如果 Key 在映射中有关联的值, 则返回 true, 否则返回 false.

MapObj.Has(Key)

Set

设置零个或多个项目.

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

这相当于用 MapObj[Key] := Value 来设置每个项目, 除了 __Item 没有被调用和 Capacity 会被自动调整, 以避免在一次调用中扩展多次.

返回值

类型: Object

此方法返回 map 对象.

__Enum

枚举键-值对.

For Key , Value in MapObj

返回一个新的枚举器. 该方法通常不直接调用. 而是将映射对象被直接传递给 for-loop, 其调用一次 __Enum 然后循环的每次迭代都调用一次枚举器. 每次对枚举器的调用都会返回下一个键和/或值. for-loop 的变量对应于枚举器的参数, 它们是:

Key

类型: 整数, 对象或字符串

键.

Value

类型: Any

值.

__New

设置项目. 等同于 Set.

MapObj.__New(Key, Value, Key2, Value2, ...)

这个方法是为了支持 Call 而存在的, 并不打算直接调用. 请参阅构造和销毁.

属性

Count

检索映射中存在的键-值对的数量.

Count := MapObj.Count

Capacity

检索或设置映射的当前容量.

MaxItems := MapObj.Capacity
MapObj.Capacity := MaxItems

MaxItems 是一个整数, 表示在必须自动扩展前, 映射可以包含的最大键-值对数量. 如果设置的值小于当前键-值对数量, 则使用设置的值并释放未使用的空间.

CaseSense

检索或设置映射的大小写敏感性设置.

CurrentSetting := MapObj.CaseSense
MapObj.CaseSense := NewSetting

如果已经赋值, CurrentSetting 为 NewSetting, 否则默认为 On(但请注意, 该属性只能检索当前设置的字符串变量).

NewSetting 是以下字符串或整数(布尔值) 之一:

On 或 1(true): 键查找区分大小写. 这是默认设置.

Off 或 0(false): 键查找不区分大小写, 即字母 A-Z 被认为与对应小写字母相同.

Locale: 根据当前用户的区域设置规则, 键查找不区分大小写. 例如, 大多数英语和西欧地区不仅将字母 A-Z视为与其对应的小写字母相同, 而且将非 ASCII 字母(如 Ä 和 Ü) 视为与其对应的字母相同. Locale 比 Off 慢 1 到 8 倍, 具体取决于所比较字符串的性质.

如果 Map 不是空的, 尝试为该属性赋值将导致抛出异常.

Default

定义当没有找到键时返回的默认值.

MapObj.Default := Value

默认情况下, 这个属性实际上并不存在, 但可以由脚本定义. 如果定义了, 如果无法找到请求的项, 则由 __Item 或 Get 返回其值, 而不是抛出 UnsetItemError. 它可以通过任何正常的方式来实现, 包括动态属性或元函数, 但确定哪个键被查询到, 需要覆盖 __Item 或 Get 来代替.

__Item

检索或设置键-值对的值.

Value := MapObj[Key]
Value := MapObj.__Item[Key]
MapObj[Key] := Value
MapObj.__Item[Key] := Value

检索值时, Key 必须是先前与另一个值关联的唯一值. 如果 Key 在映射中没有关联的值, 则抛出 UnsetItemError, 除非定义了 Default 属性, 在这种情况下返回其值.

赋值时, 与 Value 关联的 Key 可以是任何值; 换句话说, key 用于以后访问 Value. 浮点键会自动转换为字符串.

如上所示, 属性名 __Item 通常被省略, 但在覆盖属性时使用.