存取键值表
【E2EE文档】

存取键值表

[存取键值表]对象相当于一本字典。比较通用的名称叫做“哈希表”或者“键值对”,它可以通过名称快速的获取和设置数据内容。

在以下内容中,将使用别名“键值表”来表示[存取键值表]。

存取键值表是无序的。数据的顺序和添加/加载顺序无关。

键值表在多种编程语言中被广泛应用

键值表由于其出色的性能,灵活的赋值方式,成为一种通用的逻辑解耦形式,被广泛应用在各种主流语言中。以下是键值表在其它语言中的常见对象名称:

  • [Java] Map
  • [JavaScript] Object
  • [C#] Dictionary
  • [PHP] Array

支持的数据类型

键值表的名称为文本型,值可以为以下类型:

  • 空类型(没有任何实际内容)
  • 整数型
  • 长整数型
  • 小数型
  • 双精度小数型
  • 逻辑型
  • 文本型
  • 宽文本型(UNICODE)
  • 字节集
  • 日期时间型
  • 存取键值表
  • 存取列表

在赋值时如果值类型为[短整数型]会被自动转换为[整数型]。

快速查看键值表

要快速查看键值表的内容,可以使用 键值表.到文本 方法。作用是将键值表快速输出为便于阅读的文本内容。

注意:[到文本] 方法只适用于快速输出和调试使用!并不能从文本再次载入回键值表格式。

快速创建键值表

有两种方式可以快速创建一个键值表。我们可以通过“键值表.到文本()”来快速查看键值表的内容。

使用时通过参数的奇偶位置决定是名称还是值,奇数必须为[文本型]表示名称,偶数可以为所有键值表支持的数据类型用做值数据。

1. 通过 创建键值表 函数创建

{ 名称: JimStone 年龄: 18 }

2. 通过 键值表.创建 方法创建(建议)

键值表提供了“创建”方法,作用和“创建键值表()”函数差不多,不同的是基于已有对象进行创建和赋值操作的。

注意:执行“创建”方法时,键值表中已有的内容会被清空。

{ 名称: JimStone 年龄: 18 }

建议使用“键值表.创建”方法

“创建键值表”函数会返回键值表,当使用 “A = 创建键值表()”这样的语句时,结果相当于创建了键值表,然后再次进行了一次拷贝结果到“A”变量中。

“键值表.创建”方法在多线程中也会更加稳定。

多线程中建议最好不要使用“创建键值表”。仅在一些一次性资源初始化的环节中,可以少量使用“创建键值表”函数:

赋值

键值表赋值和取值时,通过使用方法的[主键]参数(文本型)做为“字典”的索引或者名称,来获取和设置对应的内容的。

类型赋值

赋值方法的名称以“”开头,后边带类型名称,例如“置整数”就是设置内容为指定的整数数值,其它的如“置文本”或“置字节集”可设置内容为文本或字节集。

{ 名称: JimStone 年龄: 18 }

目前支持的类型赋值方法

  • 置文本
  • 置整数
  • 置长整数
  • 置小数
  • 置双精度小数
  • 置逻辑值
  • 置时间
  • 置字节集
  • 置宽文本 (UNICODE)
  • 置宽文本_编码 (UNICODE)
  • 置列表 (存取列表)
  • 置键值表 (存取键值表)

通用赋值

您可以直接使用“置值”方法,把任意类型的参数做为值传递给键值表,它会自动匹配类型并进行赋值操作。

{ 名称: JimStone 年龄: 18 }

通用赋值支持上文中枚举出来的[支持的数据类型],其中不包含宽文本和其它数据类型。

赋值为空

要给一个结果赋值为[空] (null)类型的结果,可以直接使用“键值表.置为空值”方法。

注意:[空]值不是不存在,空只是一种特殊状态的存在。置为空值 和 删除 是不同的操作。删除后“主键”也将被一同删除,但是 置为空值 只是设置结果为[空]状态,其主键还是存在的,可以通过“取类型”得到对应的类型为“存取类型_空”。

连续赋值

连续赋值可以使用“键值表.连续置值”方法,作用和用法与“键值表.创建”方法类似,不同的是在使用时,不会清空现有键值表中的内容

{ 名称: JimStone 年龄: 18 }

选择性赋值

“连续填充”方法可以根据键值表中当前内容的状态,进行赋值操作。支持以下赋值条件:

  • [0] 填充所有键值(作用等同于 连续置值)
  • [1] 仅填充键值表中不存在或类型为[空]的值
  • [2] 仅填充键值表中存在且类型不为[空]的值

可以使用“#键值填充类型_”开头的常量,指定填充类型。

从JSON文本赋值

您可以通过一段JSON文本做为值,赋值给指定的[主键]。JSON文本在赋值后,将自动转化为键值表内支持的数据类型。譬如如果是“Array”(JSON文本中中括号“[]”包裹的内容)将被解析为[存取列表]类型的值,而“Object”(JSON文本中大括号“{}”包裹的内容)将被解析为[存取键值表]。

{ 用户: { 名称: JimStone 年龄: 18 } }

取值

类型取值

取值可以直接通过“”加类型名获取结果。例如“取文本”/“取整数”。

* JimStone

* 18

目前支持的类型取值方法

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

注意

当类型不同时,键值表会尝试自动转换对应数据类型为指定的数据类型。假如值为文本型内容“18”,通过“取整数”会自动转换为整数18。

以下为类型不匹配时转换失败时各个方法返回的结果:

  • 取文本 : 返回空文本 “”
  • 取整数 : 返回 [0]
  • 取长整数 : 返回 [0]
  • 取小数 : 返回 [0]
  • 取双精度小数 : 返回 [0]
  • 取逻辑值 : 返回 [假]
  • 取时间 : 返回 “1899年12月30日”
  • 取字节集 : 返回空字节集 {}
  • 取宽文本(UNICODE) : 返回空文本 “”

取值为JSON文本

键值表支持将指定的值直接转换为JSON文本。

{ "名称": "JimStone", "年龄": 18 }

值类型为[键值表]返回为[Object]类型JSON

当值类型为[存取键值表]时,返回[Object]类型的JSON文本,以大括号“{}”包裹。

值类型为[存取列表]返回为[Array]类型JSON

当值类型为[存取列表]时,返回[Array]类型的JSON文本,以中括号“[]”包裹。

值类型为[文本型]时返回为[String]类型JSON

[String]类型JSON以半角双引号开始和结束。如果内容中包含换行或双引号则自动使用转义符号代替原内容。具体可以查看JSON官网

寻址表达式

键值表支持 类JSON式 寻址方式,我们称之为[寻址表达式]。

键值表对象是复合式对象。值除了支持基础数据类型外,还可以使用[存取键值表]和[存取列表]类型的对象,要快速获取和设置这些对象中的内容时,就可以用到[寻址表达式]。

使用约定

  • 表达式必须以“//”开头

  • 多级别内容使用“.”进行区分

  • 指向[存取键值表]下的内容

    • 用[主键]名称表示

      • 例如:主键1
      • 例如:主键1.主键2
  • 指向[存取列表]下的内容

    • 用大括号包含索引的方式

      • 例如:[1]
      • 例如:主键1.[1]
    • 列表索引从1开始

    • 多级别时可省略“.”

      • 例如:主键1[1]
  • 主键名包含关键字时在前面加“\”进行转义

    • 关键字列表

      • [
      • ]
      • {
      • }
      • .
      • /
    • 容易产生歧义建议尽少使用

使用方法

在 取值 和 赋值 时,用[寻址表达式]代替[主键]参数即可。例如:键值表.取文本("//名称")

示例

我们通过以下内容来了解下具体的[寻址表达式]使用方法。

其中“{}”中的内容指向[存取键值表],“[]”中的内容指向[存取列表]。

获取“名称”

JimStone

获取“组织”下的“职位”

CTO

获取“技能”下的第1条数据

C++

获取“技能”下的第4条数据

易语言

获取“群组”下第2条下的“名称”

E2EE 测试群

枚举键值表

要枚举一个键值表,可以直接使用“取键数组”方法,获取所有主键的名称数组,然后通过枚举数组每一个主键,获取内容或类型等信息。

* 主键数量:2

* [主键] 名称

*   [类型] 6

*   [内容] JimStone

* [主键] 年龄

*   [类型] 1

*   [内容] 18

常用方法

删除

根据主键名称删除对应的数据。

清空

清空当前键值表中所有的数据。

取类型

获取值数据的类型可以使用“键值表.取类型”方法。返回内容可以通过和以下常量进行比较来判断具体类型。

  • #存取类型_空 : 空类型
  • #存取类型_整数型 : 整数型
  • #存取类型_长整数型 : 长整数型
  • #存取类型_小数型 : 小数型
  • #存取类型_双精度小数型 : 双精度小数型
  • #存取类型_逻辑型 : 逻辑型
  • #存取类型_时间型 : 日期时间型
  • #存取类型_字节集 : 字节集
  • #存取类型_文本型 : 宽文本型(UNICODE)
  • #存取类型_宽文本型 : 文本型
  • #存取类型_存取列表 : 存取列表
  • #存取类型_存取键值表 : 存取键值表

当[主键]不存在时通过“取类型”方法返回的是[空类型]。您可以使用“是否存在”方法来判断一个主键和对应的值是否存在(空也返回[真])。

以下函数实现可以用来输出键值表和对应主键的类型:

取数量

返回整个键值表中键值对的数量。

是否存在

判断并返回指定[主键]是否存在。如果主键对应的值类型为[空]也将返回[真]。

是否为空值

判断指定[主键]的值是否为[空]类型。[空]值或者不存在值的情况下,均返回[真]。

合并到

合并当前键值表到指定键值表中。

序列化和反序列化

键值表除了作为常用的数据存储对象外,还能够将内容序列化输出,和反序列化载入。

键值表支持的序列化格式

  • JSON
  • 字节集
  • Base64
  • XML(不支持属性)

注意:键值表的字节集和Base64格式,只支持键值表类型本身的载入,并不适用于任何其它流处理对象。

JSON

从JSON载入数据

  • 键值表.从JSON载入

参数说明

[JSON数据] 要载入的JSON文本内容。支持 文本 和 字节集 类型的数据。如果JSON文本内容不为对象类型(Object)则载入失败。对象类型格式为“{”开头“}”结束,例如:{ "name": "E2EE" }。数组类型(Array)的JSON文本请使用“存取列表”类型对象载入。

[来源编码类型] 要载入的JSON文本的编码类型。由于键值表支持UNICODE,所以指定非GBK类型的内容时,通过本参数直接告诉键值表编码格式,他将根据情况自动载入为UNICODE格式内容。

[是否转换UNICODE] 指定是否来源的JSON中包含UNICODE转义字符(以“\u”开头的文本内容)。如果不设置,则自动根据内容判断是否包含UNICODE转义字符。

生成JSON文本

  • 键值表.到JSON

[是否修饰] 指定是否修饰输出的JSON文本。修饰后输出的内容更便于阅读。效率会稍微低一点。修饰后,输出的JSON每条数据之间会包含换行符,下级元素的行首会增加多余的空格表示缩进级别。

[是否UNICODE] 是否输出为包含UNICODE转义的文本。如果为空则默认为假,如果为真,则ASCII外的字符(中文等)将转换为UNICODE,并转换为以“\u”开头四位十六进制文本的内容。转义后的内容在标准的JSON系统中,只要支持UNICODE转义,都可以正确识别内容。

[主键排序方式] 当前键值表和所有下级键值表输出时的主键排序方式。[0] 不排序 [1] 正向排序 [2] 反向排序。如果为空则默认为0。

字节集

  • 键值表.到字节集
  • 键值表.从字节集载入

载入的内容必须为“键值表.到字节集”后的内容,否则会载入失败。

Base64

  • 键值表.到Base64
  • 键值表.从Base64载入

载入的内容必须为“键值表.到Base64”后的内容,否则会载入失败。

XML

键值表只支持没有属性的XML生成和加载。如果载入时有属性信息,则属性会被自动忽略。

  • 键值表.到XML
  • 键值表.从XML载入

如果需要属性等支持的XML解析功能,可以使用 网页内容解析器 对象。

从指定来源载入

键值表支持以常用的IO方式,加载键值表数据。数据来源可以为以下序列化后的格式:

  • JSON
  • 字节集
  • Base64

从文件载入

  • 键值表.从文件载入

从指定文件加载键值表。

从网络载入

  • 键值表.从网络载入

从指定网址加载键值表。成功返回[真]。

可以指定[编码]、[请求头]、[超时]或[发送数据] (用于POST)等参数。

标准数据反馈模型

键值表通过使用固定名称的主键来描述信息的状态和结果,作为标准的反馈数据载体,用于多种场景下数据交换使用,这种格式我们称为[标准数据反馈模型],我们可以用更简略的名称[反馈模型]用来表示[标准数据反馈模型]。

在E2EE中用于[反馈模型]的键值表,拥有以下四个固定名称的[主键] (不包含中括号):

  • [stat] 消息状态。逻辑型。用于表达数据是否处理成功。
  • [code] 消息编号。整数型。用来描述错误类型的编号等。
  • [msg] 消息说明。文本型。用于描述数据成功或者失败时需要展示给用户的内容。
  • [data] 消息数据。通用型。允许为空。通常在成功时,用来承载具体的数据返回结果。

通过以上四个固定[主键],可以描述一条数据处理的大部分信息。

创建[反馈模型]数据

  • 键值表.创建消息
  • 键值表.创建消息_宽文本(UNICODE)

通过[创建消息]方法可以快速的创建反馈数据。使用时原数据内容将被清空。

在[视图函数]中使用[反馈模型]

在网站[视图函数]中,可以通过[服务器响应]对象的以下方法,直接写出标准反馈模型数据([响应]用于表示[服务器响应]对象)。

  • 响应.写出成功
  • 响应.写出成功_宽文本
  • 响应.写出失败
  • 响应.写出失败_宽文本
  • 响应.写出结果
  • 响应.写出结果_宽文本

注意[响应]对象写出的反馈模型数据,在不同的场景下,可能返回的数据格式也不同。譬如在正常环境中,写出的是JSON文本,而在WebService环境中,会直接写出XML。如果视图函数用于[远程服务]时,则直接返回远程服务要求的JSON格式。

文件同步

[键值表]可以通过绑定文件路径的方式,快速从文件载入和写入数据。相关的方法,主要适用于把[键值表]做为软件配置等场景下。通过[打开文件]绑定路径后,直接调用[保存文件]可直接将内容写入到打开的路径中。

相关方法

  • 键值表.打开文件
  • 键值表.保存文件
  • 键值表.关闭文件
  • 键值表.另存文件

使用流程

1. 打开文件

通过使用[打开文件]方法,能够快速把[键值表]和指定的[文件路径]以及文件的格式(JSON、字节集或Base64)做绑定。如果打开的文件不存在,也将返回[真]。读入失败时会返回[假],失败时文件路径和格式依然会被记录下来,继续作用于[保存文件]等方法中。

2. 保存文件

打开成功后,在修改键值表内容之后,可以使用[保存文件]方法将[键值表]数据,按照打开时指定的文件和格式写入。

内存处理

避免内存复制

[键值表]对象的所有赋值操作,都是通过拷贝数据的方式执行的,只有在使用以下方法时,可以避免对象内存复制,加快数据处理效率:

  • 键值表.置键值表
  • 键值表.置列表

使用时通过指定[是否交换内容]参数为[],通过对象内容交换的方式,避免[复合对象]的内存复制操作。

在动态链接库(DLL)中传递[键值表]

您可以通过[打包对象]和[解包对象]的方式,将键值表转换为整数,在您的主程序中和动态链接库(DLL)或其它子程序中进行传递。

  • 键值表.打包对象
  • 键值表.解包对象

打包对象

[打包对象]方法可以将当前键值表,直接转换为[整数型]的指针地址,并且将原键值表的指向地址自动清空。

在使用[打包对象]方法后,当前键值表的指向已经被清理,请不要继续对键值表进行操作,否则可能会产生难以预计的后果(程序崩溃等)。

解包对象

[解包对象]方法可以将当前键值表,直接替换为从[打包对象]的指针指向的键值表。使用时原键值表的内容将被自动清空和删除,键值表将被重定向到参数指定的地址。如果传入的地址为0,则返回[假]。

注意:在没有理解[打包对象]和[解包对象]的特性时,请不要轻易用于正式项目,否则可能会导致程序不稳定(崩溃等)。

扩展方法

到表单文本

键值表.到表单文本 将键值表序列化为表单文本。表单文本将被执行URL编码处理。

主键更名

键值表.主键更名 更改键值表中的主键名称。原始名称的主键必须存在,目标名称主键不能存在,参数个数只能为复数,单数为原主键名称,复数为新主键名称。否则返回失败。

键值互换

键值表.键值互换 生成键值互换之后的键值表。新的键为原键值表的 取文本() 生成的内容,数值、日期、字节集等等会被转换为文本,如果同一个值作为主键同时存在多个键值,则只会保留最后一个结果(由于键值表的存储结构可能会造成结果的随机性)。

子列表排序

键值表.子列表排序 对键值表中的子列表进行排序。

子列表添加

键值表.子列表添加 对键值表中的子列表进行添加值的操作。其中主键指向的值类型必须为[存取列表]类型时才有效。

子列表删除

键值表.子列表删除 对键值表中的子列表进行删除操作。其中主键指向的值类型必须为[存取列表]类型时才有效。