# 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 并设置项目.
- 方法:
  - Clear: 从映射中删除所有键-值对.
  - Clone: 返回对象的一个浅拷贝.
  - Delete: 从映射中删除键-值对.
  - Get: 返回键关联的值, 或者一个默认值.
  - Has: 如果 Key 在映射中有关联的值, 则返回 true.
  - Set: 设置零个或多个项目.
  - __Enum: E枚举键-值对.
  - __New: 设置项目. 等同于 Set.
- 属性:
  - Count: 检索映射中存在的键-值对的数量.
  - Capacity: 检索或设置映射的当前容量.
  - CaseSense: 检索或设置映射的大小写敏感性设置.
  - Default: 定义当没有找到键时返回的默认值.
  - __Item: 检索或设置键-值对的值.

## 静态方法

### Call

创建一个 Map 并设置项目.

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

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

参数由 __New 定义.

## 方法

### Clear

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

    MapObj.Clear()

### Clone

返回对象的一个浅拷贝.

    Clone := MapObj.Clone()

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

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

### Delete

从映射中删除键-值对.

    MapObj.Delete(Key)

Key

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

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

返回删除的值.

### Get

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

    Value := MapObj.Get(Key , Default)

此方法执行以下操作:

- 返回与 Key 关联的值, 如果找到.
- 如果 Default 参数的值, 如果指定.
- 返回 `MapObj.Default` 的值, 如果定义.
- 抛出 UnsetItemError.

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

### Has

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

    MapObj.Has(Key)

### Set

设置零个或多个项目.

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

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

返回 map 对象.

### __Enum

枚举键-值对.

    For Key , Value in MapObj

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

Key

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

  键.

Value

  值.

### __New

设置项目. 等同于 Set.

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

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

## 属性

### Count

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

    Count := MapObj.Count

### Capacity

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

    MapObj.Capacity := MaxItems

    MaxItems := MapObj.Capacity

MaxItems

  类型: 整数

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

### CaseSense

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

    MapObj.CaseSense := Setting

    Setting := MapObj.CaseSense

Setting

  类型: 字符串

  以下值之一:

  `"On"`: 键查询区分大小写. 这是默认设置.

  `"Off"`: 字母 A-Z 被视为与其小写字母相同.

  `"Locale"`: 根据当前用户的区域设置规则, 键查询不区分大小写. 例如, 在大多数英语和西欧地区, 不仅将字母 A-Z 视为与其小写字母相同, 而且也将非 ASCII 字母如 Ä 和 Ü 视为与其小写字母相同. 根据被比较字符串的性质, Locale 比 Off 慢 1 到 8 倍.

  在赋值时, 也可以使用字符串 `"1"` 和 `"0"`.

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

### Default

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

    MapObj.Default := Value

默认情况下, 这个属性实际上并不存在, 但可以由脚本定义. 当脚本查询一个键没有找到时, map 会在抛出 UnsetItemError 之前检查这个属性. 它可以通过任何正常的方式来实现, 包括动态属性或元函数, 但确定哪个键被查询到, 需要覆盖 __Item 或 Get 来代替.

### __Item

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

    Value := MapObj[Key]

    MapObj[Key] := Value

Key

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

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

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

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

dftg