通用存取对象
【E2EE文档】

通用存取对象

E2EE内置了两种高效的通用存取值用的对象。为了不与其它支持库数据类型名称产生冲突,都使用“存取”开头。

  • 存取键值表:字典对象
  • 存取列表:列表对象

本章节索引:

  1. 存取键值表
  2. 存取列表
  3. 通用方法

通用存取对象支持的数据类型:

  • 整数
  • 长整数
  • 小数
  • 双精度小数
  • 逻辑型
  • 文本
  • 字节集
  • 日期时间
  • 存取键值表(自)
  • 存取列表(自)

支持的数据类型中比易语言少了 短整数型、字节型的,主要是为了更加通用。

1. 存取键值表

存取键值表本身是一种高效的字典对象。

存取键值表的文本展开形式大概如下:

{
    昵称: "JimStone"
    姓名: "谢栋"
    性别: "男"
    身高: 172
}

昵称 和 姓名等为主键,右边的内容为值。

1.1 赋值

存取键值表的所有赋值操作均以“置”字开头,赋值时第一个参数[主键]永远都是“文本型”。

  • 置整数()
  • 置长整数()
  • 置小数()
  • 置双精度小数()
  • 置逻辑型()
  • 置文本()
  • 置字节集()
  • 置日期时间()
  • 置键值表()
  • 置列表()

使用方式如下:

键值表.置文本 (“标题”, “来三碗82年的拉飞”)
键值表.置整数 (“端口”, 8080)

当然也允许使用通用型(只允许数据类型为上面枚举的内部支持的数据类型):

键值表.置值 (“标题”, “来三碗82年的拉飞”)
键值表.置值 (“端口”, 取整 (8080))

注意:当使用通用型的时候,易语言通常会把魔法整数当做“双精度小数型”来对待,所以对于整数最好的做法是将数值使用“取整()”包裹一下,保证数据类型的准确性。就如上面的 取整(8080)。

赋值操作允许嵌套同类型的数据,但不允许值为对象本身。

当赋值为 存取键值表 和 存取列表 的时候,赋值的内容为 值对象的副本,而不是值对象本身。

.局部变量 分页列表, 存取列表
.局部变量 模板数据, 存取键值表
...
模板数据.置值 (“分页列表”, 分页列表)
...
分页列表.添加值 (120)

这种情况下,“模板数据”的“分页列表”值不会产生任何变化,用 模板数据.取列表(“分页列表”) 返回的对象是不包含 120 的。因为在赋值时,值是从 分页列表 对象复制出来的副本。基于这种特性,键值表和列表之间永远不会产生互相包含的情况。

1.2 取值

存取键值表的所有取值操作均以“取”字开头,取值时和赋值操作一样,第一个参数[主键]永远都是“文本型”。

  • 取整数()
  • 取长整数()
  • 取小数()
  • 取双精度小数()
  • 取逻辑型()
  • 取文本()
  • 取字节集()
  • 取日期时间()
  • 取键值表()
  • 取列表()

使用方式如下:

标题 = 键值表.取文本 (“标题”)
端口 = 键值表.取整数 (“端口”)

取值失败主要有以下几种情况:

  • 主键不存在
  • 数据类型不匹配/无法转换

取值失败时会返回空的数据:

  • 数值类型:返回 0
  • 逻辑型:返回 假
  • 日期时间:返回 日期时间型的空
  • 文本:返回 空文本
  • 字节集:返回 空字节集

取值时有两种通用取值情况:

  • 数值类型数据间 支持自动转换
    • 您可以通过 取长整数() 来获取一个 整数型 的值,注意数据类型长度缩减时可能数值会被自动截断从而产生问题,所以无法保证数据类型长度的时候,不建议通过取长数据值的方式获取短数据类型(譬如 整数型 和长整数,小数型 和 双精度浮点型).
  • 取文本() 支持所有类型的数据
    • 数值:自动转换为文本
    • 逻辑型:根据 真 / 假 输出小写 true / false
    • 存取键值表 和 存取列表 类型:返回它们 到文本() 方法产生的内容,是一种类似 JSON 的文本
    • 日期时间型:转换为 yyyy-MM-dd HH:mm:ss 的格式。例如:2017-03-23 04:54:00
    • 字节集:输出连续的十六进制文本。例如:FF 0A C3 4D

允许使用通用型取值,通过通用型取值时要先确保数据类型跟您的变量类型绝对一致,否则易语言会报错。

使用通用型取值示例:

标题 = 键值表.取值 (“标题”)
端口 = 键值表.取值 (“端口”)

1.3 取键数组

键值表.取键数组() 命令能够获取到当前键值表的所有主键。返回类型为 文本型数组。

.局部变量 主键数组, 文本型, , "0"
主键数组 = 模板数据.取键数组 ()

您可以通过枚举数组的方式来获取所有键值表的值内容。

1.4 取类型

键值表.取类型(主键) 返回指定主键的值的类型。类型常量主要有以下几种:

当对应的主键不存在时,会返回“存取类型_空”的值。

1.5 是否存在

键值表.是否存在(主键) 判断某个主键是否存在。

2. 存取列表

存取列表相当于数组对象,存取列表本身擅长添加操作,插入和删除的效率一般。

存取列表的文本展开形式大概如下:

[
    "JimStone"
    "谢栋"
    "男"
    172
]

昵称 和 姓名等为主键,右边的内容为值。

存取列表 的使用方式 和 存取键值表 基本差不多,取值赋值命令主要包含以下4中类型:

  • 取值
  • 置值
  • 添加值
  • 插入值

取值 和 置值 操作的第一个参数为整数型,指向数据的位置索引,跟数组一样是从1开始的。

2.1 取值

以“”开头,跟随数据类型名称。例如:取整数()。允许通用型方法 取值()

使用说明 存取键值表 的 取值

2.2 置值

以“”开头,跟随数据类型名称。 例如:置整数()。允许通用型方法 置值()

置值失败会返回 ,通常置值失败的原因为数据的位置索引超出列表范围。置值成功会替换指定位置的数据。

使用方式参考 存取键值表 的 置值

2.3 添加值

以“添加”开头,跟随数据类型名称。 例如:添加整数()。允许通用型方法 添加值()

添加值是将数据加到当前列表的尾部。

第二个参数支持无限参数。

使用方式参考 存取键值表 的 置值

2.4 插入值

以“插入”开头,跟随数据类型名称。 例如:插入整数()。允许通用型方法 插入值()

第一个参数插入的位置从1开始,允许负数。

  • 为 1 时表示插入到列表顶部
  • 负数为从尾部插入,例如-1则插入到最后一条之前。

第二个参数支持无限参数。

插入失败会返回 假。

使用方式参考 存取键值表 的 置值

2.5 删除

删除() 方法能够删除某行数据或者某范围的数据。

删除命令的参数有以下两个:

-   索引: 要删除的索引位置。从1开始。如果为负数,则从后删除,如:[-1]删除最后一个。
-   删除数量:总删除数量不能超出删除范围。如果为空则只删除1条,如果为 -1 则删除后边所有。可以忽略,忽略时只删除索引指向的一条记录。

2.6 取数量

取数量() 方法返回当前列表的数据行数。

2.7 其它方法

取类型()、是否为空() 和 取文本() 的使用方法和 存取键值表 对应名称的方法一样。唯一的区别是,参数传入的是数据位置的索引而不是主键。

3. 通用方法

这里的通用方法指的是命名和使用形式 在 存取键值表 和 存取列表 之间完全一样的方法。

3.1 清空

清空当前对象的所有数据。

3.2 到文本

到文本() 方法将以文本的形式返回当前对象的数据内容,文本的格式类似于 JSON。和JSON之间最大的区别为 主键名 和 值 文本的外层是不包含引号的。

3.3 到JSON 和 从JSON载入

到JSON() 能够将当前对象转换为JSON文本,列表会返回JSON数组格式的内容。键值表会返回JSON字典格式的内容。

从JSON载入() 能够将JSON转为 存取键值表 或 存取列表 对象。

在做JSON输出和载入时,并不是所有的数据类型都支持转换,对象会以这种的方式处理生成数据。

生成JSON时典型的折中处理的情况主要有以下几种:

  • 日期时间型:生成时会被转换为 日期时间的 文本,格式为 yyyy-MM-dd HH:mm:ss。例如:2017-03-23 04:54:00。载入时还是为文本。原因是JSON中不存在日期时间型的类别。
  • 字节集:生成JSON时会被转换为Base64文本。但当从JSON载入的时候,读入的还是Base64后的文本型数据。
  • 整数型:生成正常,但是载入时会被转换为 长整数。
  • 小数型:生成正常,但是载入时会被转换为 双精度小数型。

3.4 合并到

将当前的 存取键值表 和 存取列表 当前的数据,并入到其它同类型的对象中。

存取列表时 列表数据会被加入对应列表的尾部。

存取键值对 是无序的,所以没有插入尾部的说法。

3.5 快速创建通用对象

在支持库的“对象工厂”下提供了两个辅助函数,能够帮助您快速创建通用对象:

  • 创建键值表(通用型 键值)
  • 创建列表 (通用型 值)

通过这两个方法,您就能够快速的构建 存取键值表 和 存取列表了。

创建键值表函数

创建键值表() : 存取键值表

    键值:“通用型”。键/值内容。单数为键,复数为值。

创建一个键值表。格式单数为键,复数为值。如果键不为文本则不会插入,值类型只支持存取键值表支持的类型,不支持的将不会被插入新对象中。

创建键值表(“名称”, “谢栋”, “性别”, “男”, “年龄”, 30)

此时生成的键值表文本展开形式如下:

{
    名称: "谢栋"
    性别: "男"
    年龄: 30
}   

注意:如果第一个值名称为“*”,当第二个值也为文本型时,将使用第二个值做为名称在外部包裹一层[存取键值表]。主要用于模板过滤处理。

创建列表函数

创建列表() : 存取列表

:“通用型”。值内容。仅支持存取列表支持的类型。

创建一个列表。值类型只支持存取列表支持的类型。存在不支持的类型返回空列表。

创建列表(“谢栋”, 真, 30)

此时生成的列表文本展开形式如下:

[
    "谢栋"
    真
    30
]