[E2EE文档2.x] 存取键值表
[存取键值表]对象相当于一本字典。比较通用的名称叫做“哈希表”或者“键值对”,它可以通过名称快速的获取和设置shuj内容。
在以下内容中,将使用别名“键值表”来表示[存取键值表]。
存取键值表是无序的。shuj的顺序和添加/加载顺序无关。
键值表在多种编程语言中被广泛应用
键值表由于其出色的性能,灵活的赋值方式,成为一种通用的逻辑解耦形式,被广泛应用在各种主流语言中。以下是键值表在其它语言中的常见对象名称:
- [Java] Map
- [JavaScript] Object
- [C#] Dictionary
- [PHP] Array
支持的shuj类型
键值表的名称为文本型,值可以为以下类型:
- 空类型(没有任何实际内容)
- 整数型
- 长整数型
- 小数型
- 双精度小数型
- 逻辑型
- 文本型
- 宽文本型(UNICODE)
- 字节集
- 日期时间型
- 存取键值表
- 存取列表
在赋值时如果值类型为[短整数型]会被自动转换为[整数型]。
快速查看键值表
要快速查看键值表的内容,可以使用 键值表.到文本 方法。作用是将键值表快速输出为便于阅读的文本内容。
注意:[到文本] 方法只适用于快速输出和调试使用!并不能从文本再次载入回键值表格式。
快速创建键值表
有两种方式可以快速创建一个键值表。我们可以通过“键值表.到文本()”来快速查看键值表的内容。
使用时通过参数的奇偶位置决定是名称还是值,奇数必须为[文本型]表示名称,偶数可以为所有键值表支持的shuj类型用做值shuj。
1. 通过 创建键值表 函数创建
.版本 2
.支持库 e2ee
.子程序 快速创建键值表1
.局部变量 键值表, 存取键值表
键值表 = 创建键值表 (“名称”, “JimStone”, “年龄”, 18)
输出调试文本 (键值表.到文本 ())
{
名称: JimStone
年龄: 18
}
2. 通过 键值表.创建 方法创建(建议)
键值表提供了“创建”方法,作用和“创建键值表()”函数差不多,不同的是基于已有对象进行创建和赋值操作的。
注意:执行“创建”方法时,键值表中已有的内容会被清空。
.版本 2
.支持库 e2ee
.子程序 快速创建键值表2
.局部变量 键值表, 存取键值表
' 通过 键值表.创建 方法创建
键值表.创建 (“名称”, “JimStone”, “年龄”, 18)
输出调试文本 (键值表.到文本 ())
{
名称: JimStone
年龄: 18
}
建议使用“键值表.创建”方法
“创建键值表”函数会返回键值表,当使用 “A = 创建键值表()”这样的语句时,结果相当于创建了键值表,然后再次进行了一次拷贝结果到“A”变量中。
“键值表.创建”方法在多线程中也会更加稳定。
多线程中建议最好不要使用“创建键值表”。仅在一些一次性zy初始化的环节中,可以少量使用“创建键值表”函数:
服务器.启动 (创建键值表(#配置项_端口, 8080))
赋值
键值表赋值和取值时,通过使用方法的[主键]参数(文本型)做为“字典”的索引或者名称,来获取和设置对应的内容的。
类型赋值
赋值方法的名称以“置”开头,后边带类型名称,例如“置整数”就是设置内容为指定的整数数值,其它的如“置文本”或“置字节集”可设置内容为文本或字节集。
.版本 2
.支持库 e2ee
.子程序 类型赋值
.局部变量 键值表, 存取键值表
键值表.置文本 (“名称”, “JimStone”)
键值表.置整数 (“年龄”, 18)
输出调试文本 (键值表.到文本 ())
{
名称: JimStone
年龄: 18
}
目前支持的类型赋值方法
- 置文本
- 置整数
- 置长整数
- 置小数
- 置双精度小数
- 置逻辑值
- 置时间
- 置字节集
- 置宽文本 (UNICODE)
- 置宽文本_编码 (UNICODE)
- 置列表 (存取列表)
- 置键值表 (存取键值表)
通用赋值
您可以直接使用“置值”方法,把任意类型的参数做为值传递给键值表,它会自动匹配类型并进行赋值操作。
.版本 2
.支持库 e2ee
.子程序 通用赋值
.局部变量 键值表, 存取键值表
键值表.置值 (“名称”, “JimStone”)
键值表.置值 (“年龄”, 18)
输出调试文本 (键值表.到文本 ())
{
名称: JimStone
年龄: 18
}
通用赋值支持上文中枚举出来的[支持的shuj类型],其中不包含宽文本和其它shuj类型。
赋值为空
要给一个结果赋值为[空] (null)类型的结果,可以直接使用“键值表.置为空值”方法。
注意:[空]值不是不存在,空只是一种特殊状态的存在。置为空值 和 删除 是不同的操作。删除后“主键”也将被一同删除,但是 置为空值 只是设置结果为[空]状态,其主键还是存在的,可以通过“取类型”得到对应的类型为“存取类型_空”。
连续赋值
连续赋值可以使用“键值表.连续置值”方法,作用和用法与“键值表.创建”方法类似,不同的是在使用时,不会清空现有键值表中的内容。
.版本 2
.支持库 e2ee
.子程序 连续赋值
.局部变量 键值表, 存取键值表
键值表.连续置值 (“名称”, “JimStone”, “年龄”, 18)
输出调试文本 (键值表.到文本 ())
{
名称: JimStone
年龄: 18
}
选择性赋值
“连续填充”方法可以根据键值表中当前内容的状态,进行赋值操作。支持以下赋值条件:
- [0] 填充所有键值(作用等同于 连续置值)
- [1] 仅填充键值表中不存在或类型为[空]的值
- [2] 仅填充键值表中存在且类型不为[空]的值
可以使用“#键值填充类型_”开头的常量,指定填充类型。
从JSON文本赋值
您可以通过一段JSON文本做为值,赋值给指定的[主键]。JSON文本在赋值后,将自动转化为键值表内支持的shuj类型。譬如如果是“Array”(JSON文本中中括号“[]”包裹的内容)将被解析为[存取列表]类型的值,而“Object”(JSON文本中大括号“{}”包裹的内容)将被解析为[存取键值表]。
.版本 2
.支持库 e2ee
.子程序 用JSON文本赋值
.局部变量 键值表, 存取键值表
' JSON文本内容为: { "名称": "JimStone", "年龄": 18 }
键值表.置JSON值 (“用户”, 创建文本 (“\{''名称'': ''JimStone'', ''年龄'': 18\}”, ), )
输出调试文本 (键值表.到文本 ())
{
用户: {
名称: JimStone
年龄: 18
}
}
取值
类型取值
取值可以直接通过“取”加类型名获取结果。例如“取文本”/“取整数”。
.版本 2
.支持库 e2ee
.子程序 类型赋值和取值
.局部变量 键值表, 存取键值表
键值表.置文本 (“名称”, “JimStone”)
键值表.置整数 (“年龄”, 18)
输出调试文本 (键值表.取文本 (“名称”))
输出调试文本 (键值表.取整数 (“年龄”))
* JimStone
* 18
目前支持的类型取值方法
- 取文本
- 取整数
- 取长整数
- 取小数
- 取双精度小数
- 取逻辑值
- 取时间
- 取字节集
- 取宽文本(UNICODE)
- 取列表(存取列表)
- 取键值表(存取键值表)
注意
当类型不同时,键值表会尝试自动转换对应shuj类型为指定的shuj类型。假如值为文本型内容“18”,通过“取整数”会自动转换为整数18。
以下为类型不匹配时转换失败时各个方法返回的结果:
- 取文本 : 返回空文本 “”
- 取整数 : 返回 [0]
- 取长整数 : 返回 [0]
- 取小数 : 返回 [0]
- 取双精度小数 : 返回 [0]
- 取逻辑值 : 返回 [假]
- 取时间 : 返回 “1899年12月30日”
- 取字节集 : 返回空字节集 {}
- 取宽文本(UNICODE) : 返回空文本 “”
取值为JSON文本
键值表支持将指定的值直接转换为JSON文本。
.版本 2
.支持库 e2ee
.子程序 用JSON文本赋值和取值
.局部变量 键值表, 存取键值表
键值表.置JSON值 (“用户”, 创建文本 (“\{''名称'': ''JimStone'', ''年龄'': 18\}”, ), )
输出调试文本 (键值表.取JSON值 (“用户”, 假, , ))
{ "名称": "JimStone", "年龄": 18 }
值类型为[键值表]返回为[Object]类型JSON
当值类型为[存取键值表]时,返回[Object]类型的JSON文本,以大括号“{}”包裹。
值类型为[存取列表]返回为[Array]类型JSON
当值类型为[存取列表]时,返回[Array]类型的JSON文本,以中括号“[]”包裹。
值类型为[文本型]时返回为[String]类型JSON
[String]类型JSON以半角双引号开始和结束。如果内容中包含换行或双引号则自动使用转义符号代替原内容。具体可以查看JSON官网。
寻址表达式
键值表支持 类JSON式 寻址方式,我们称之为[寻址表达式]。
键值表对象是复合式对象。值除了支持基础shuj类型外,还可以使用[存取键值表]和[存取列表]类型的对象,要快速获取和设置这些对象中的内容时,就可以用到[寻址表达式]。
使用约定
- 表达式必须以“//”开头
- 多级别内容使用“.”进行区分
- 指向[存取键值表]下的内容
- 用[主键]名称表示
- 例如:主键1
- 例如:主键1.主键2
- 指向[存取列表]下的内容
- 用大括号包含索引的方式
- 例如:[1]
- 例如:主键1.[1]
- 列表索引从1开始
- 多级别时可省略“.”
- 例如:主键1[1]
- 主键名包含关键字时在前面加“\”进行转义
- 关键字列表
- [
- ]
- {
- }
- .
- /
- 容易产生歧义建议尽少使用
使用方法
在 取值 和 赋值 时,用[寻址表达式]代替[主键]参数即可。例如:键值表.取文本("//名称")
示例
我们通过以下内容来了解下具体的[寻址表达式]使用方法。
{
名称: JimStone
年龄: 18
组织: {
公司: E2EE公司
部门: 技术部
职位: CTO
}
技能: [
C++
Java
C#
易语言
]
群组: [
{
名称: E2EE 网站敏捷开发
号码: 536544662
},
{
名称: E2EE 测试群
号码: 806166750
}
]
}
其中“{}”中的内容指向[存取键值表],“[]”中的内容指向[存取列表]。
获取“名称”
//名称
JimStone
获取“组织”下的“职位”
//组织.职位
CTO
获取“技能”下的第1条shuj
//技能.[1]
C++
获取“技能”下的第4条shuj
//技能[4]
易语言
获取“群组”下第2条下的“名称”
//群组[2].名称
E2EE 测试群
枚举键值表
要枚举一个键值表,可以直接使用“取键数组”方法,获取所有主键的名称数组,然后通过枚举数组每一个主键,获取内容或类型等信息。
.版本 2
.支持库 e2ee
.子程序 枚举键值表
.局部变量 键值表, 存取键值表
.局部变量 主键数组, 文本型, , "0"
.局部变量 i, 整数型
键值表.连续置值 (“名称”, “JimStone”, “年龄”, 18)
主键数组 = 键值表.取键数组 ()
输出调试文本 (“主键数量:” + 到文本 (取数组成员数 (主键数组)))
.计次循环首 (取数组成员数 (主键数组), i)
输出调试文本 (“[主键] ” + 主键数组 [i])
输出调试文本 (“ [类型] ” + 到文本 (键值表.取类型 (主键数组 [i])))
输出调试文本 (“ [内容] ” + 键值表.取文本 (主键数组 [i]))
.计次循环尾 ()
* 主键数量:2
* [主键] 名称
* [类型] 6
* [内容] JimStone
* [主键] 年龄
* [类型] 1
* [内容] 18
常用方法
删除
根据主键名称删除对应的shuj。
清空
清空当前键值表中所有的shuj。
取类型
获取值shuj的类型可以使用“键值表.取类型”方法。返回内容可以通过和以下常量进行比较来判断具体类型。
- #存取类型_空 : 空类型
- #存取类型_整数型 : 整数型
- #存取类型_长整数型 : 长整数型
- #存取类型_小数型 : 小数型
- #存取类型_双精度小数型 : 双精度小数型
- #存取类型_逻辑型 : 逻辑型
- #存取类型_时间型 : 日期时间型
- #存取类型_字节集 : 字节集
- #存取类型_文本型 : 宽文本型(UNICODE)
- #存取类型_宽文本型 : 文本型
- #存取类型_存取列表 : 存取列表
- #存取类型_存取键值表 : 存取键值表
当[主键]不存在时通过“取类型”方法返回的是[空类型]。您可以使用“是否存在”方法来判断一个主键和对应的值是否存在(空也返回[真])。
以下函数实现可以用来输出键值表和对应主键的类型:
.版本 2
.支持库 e2ee
.子程序 常用操作_取类型
.参数 键值表, 存取键值表, 参考
.参数 主键, 文本型, 参考
.局部变量 类型, 整数型
类型 = 键值表.取类型 (主键)
.判断开始 (类型 = #存取类型_空)
输出调试文本 (“空类型”)
.判断 (类型 = #存取类型_整数型)
输出调试文本 (“整数型”)
.判断 (类型 = #存取类型_长整数型)
输出调试文本 (“长整数型”)
.判断 (类型 = #存取类型_小数型)
输出调试文本 (“小数型”)
.判断 (类型 = #存取类型_双精度小数型)
输出调试文本 (“双精度小数型”)
.判断 (类型 = #存取类型_逻辑型)
输出调试文本 (“逻辑型”)
.判断 (类型 = #存取类型_时间型)
输出调试文本 (“日期时间型”)
.判断 (类型 = #存取类型_字节集)
输出调试文本 (“字节集”)
.判断 (类型 = #存取类型_文本型)
输出调试文本 (“文本型”)
.判断 (类型 = #存取类型_宽文本型)
输出调试文本 (“宽文本型(UNICODE)”)
.判断 (类型 = #存取类型_存取列表)
输出调试文本 (“存取列表”)
.判断 (类型 = #存取类型_存取键值表)
输出调试文本 (“存取键值表”)
.默认
输出调试文本 (“未知类型”)
.判断结束
取数量
返回整个键值表中键值对的数量。
是否存在
判断并返回指定[主键]是否存在。如果主键对应的值类型为[空]也将返回[真]。
是否为空值
判断指定[主键]的值是否为[空]类型。[空]值或者不存在值的情况下,均返回[真]。
合并到
合并当前键值表到指定键值表中。
序列化和反序列化
键值表除了作为常用的shuj存储对象外,还能够将内容序列化输出,和反序列化载入。
键值表支持的序列化格式
- JSON
- 字节集
- Base64
- XML(不支持属性)
注意:键值表的字节集和Base64格式,只支持键值表类型本身的载入,并不适用于任何其它流处理对象。
JSON
从JSON载入shuj
参数说明
[JSONshuj] 要载入的JSON文本内容。支持 文本 和 字节集 类型的shuj。如果JSON文本内容不为对象类型(Object)则载入失败。对象类型格式为“{”开头“}”结束,例如:{ "name": "E2EE" }。数组类型(Array)的JSON文本请使用“存取列表”类型对象载入。
[来源编码类型] 要载入的JSON文本的编码类型。由于键值表支持UNICODE,所以指定非GBK类型的内容时,通过本参数直接告诉键值表编码格式,他将根据情况自动载入为UNICODE格式内容。
[是否转换UNICODE] 指定是否来源的JSON中包含UNICODE转义字符(以“\u”开头的文本内容)。如果不设置,则自动根据内容判断是否包含UNICODE转义字符。
生成JSON文本
[是否修饰] 指定是否修饰输出的JSON文本。修饰后输出的内容更便于阅读。效率会稍微低一点。修饰后,输出的JSON每条shuj之间会包含换行符,下级元素的行首会增加多余的空格表示缩进级别。
[是否UNICODE] 是否输出为包含UNICODE转义的文本。如果为空则默认为假,如果为真,则ASCII外的字符(中文等)将转换为UNICODE,并转换为以“\u”开头四位十六进制文本的内容。转义后的内容在标准的JSON系统中,只要支持UNICODE转义,都可以正确识别内容。
[主键排序方式] 当前键值表和所有下级键值表输出时的主键排序方式。[0] 不排序 [1] 正向排序 [2] 反向排序。如果为空则默认为0。
字节集
载入的内容必须为“键值表.到字节集”后的内容,否则会载入失败。
Base64
- 键值表.到Base64
- 键值表.从Base64载入
载入的内容必须为“键值表.到Base64”后的内容,否则会载入失败。
XML
键值表只支持没有属性的XML生成和加载。如果载入时有属性信息,则属性会被自动忽略。
如果需要属性等支持的XML解析功能,可以使用 网页内容解析器 对象。
从指定来源载入
键值表支持以常用的IO方式,加载键值表shuj。shuj来源可以为以下序列化后的格式:
从文件载入
从指定文件加载键值表。
从网络载入
从指定网址加载键值表。成功返回[真]。
可以指定[编码]、[请求头]、[超时]或[发送shuj] (用于POST)等参数。
标准shuj反馈模型
键值表通过使用固定名称的主键来描述信息的状态和结果,作为标准的反馈shuj载体,用于多种场景下shuj交换使用,这种格式我们称为[标准shuj反馈模型],我们可以用更简略的名称[反馈模型]用来表示[标准shuj反馈模型]。
在E2EE中用于[反馈模型]的键值表,拥有以下四个固定名称的[主键] (不包含中括号):
- [stat] 消息状态。逻辑型。用于表达shuj是否处理成功。
- [code] 消息编号。整数型。用来描述错误类型的编号等。
- [msg] 消息说明。文本型。用于描述shuj成功或者失败时需要展示给用户的内容。
- [data] 消息shuj。通用型。允许为空。通常在成功时,用来承载具体的shuj返回结果。
通过以上四个固定[主键],可以描述一条shuj处理的大部分信息。
创建[反馈模型]shuj
- 键值表.创建消息
- 键值表.创建消息_宽文本(UNICODE)
通过[创建消息]方法可以快速的创建反馈shuj。使用时原shuj内容将被清空。
在[视图函数]中使用[反馈模型]
在网站[视图函数]中,可以通过[服务器响应]对象的以下方法,直接写出标准反馈模型shuj([响应]用于表示[服务器响应]对象)。
- 响应.写出成功
- 响应.写出成功_宽文本
- 响应.写出失败
- 响应.写出失败_宽文本
- 响应.写出结果
- 响应.写出结果_宽文本
注意: [响应]对象写出的反馈模型shuj,在不同的场景下,可能返回的shuj格式也不同。譬如在正常环境中,写出的是JSON文本,而在WebService环境中,会直接写出XML。如果视图函数用于[远程服务]时,则直接返回远程服务要求的JSON格式。
文件同步
[键值表]可以通过绑定文件路径的方式,快速从文件载入和写入shuj。相关的方法,主要适用于把[键值表]做为软件配置等场景下。通过[打开文件]绑定路径后,直接调用[保存文件]可直接将内容写入到打开的路径中。
相关方法
- 键值表.打开文件
- 键值表.保存文件
- 键值表.关闭文件
- 键值表.另存文件
使用流程
1. 打开文件
通过使用[打开文件]方法,能够快速把[键值表]和指定的[文件路径]以及文件的格式(JSON、字节集或Base64)做绑定。如果打开的文件不存在,也将返回[真]。读入失败时会返回[假],失败时文件路径和格式依然会被记录下来,继续作用于[保存文件]等方法中。
2. 保存文件
打开成功后,在修改键值表内容之后,可以使用[保存文件]方法将[键值表]shuj,按照打开时指定的文件和格式写入。
内存处理
避免内存复制
[键值表]对象的所有赋值操作,都是通过拷贝shuj的方式执行的,只有在使用以下方法时,可以避免对象内存复制,加快shuj处理效率:
使用时通过指定[是否交换内容]参数为[真],通过对象内容交换的方式,避免[复合对象]的内存复制操作。
在动态链接库(DLL)中传递[键值表]
您可以通过[打包对象]和[解包对象]的方式,将键值表转换为整数,在您的主程序中和动态链接库(DLL)或其它子程序中进行传递。
打包对象
[打包对象]方法可以将当前键值表,直接转换为[整数型]的指针地址,并且将原键值表的指向地址自动清空。
在使用[打包对象]方法后,当前键值表的指向已经被清理,请不要继续对键值表进行操作,否则可能会产生难以预计的后果(程序崩溃等)。
解包对象
[解包对象]方法可以将当前键值表,直接替换为从[打包对象]的指针指向的键值表。使用时原键值表的内容将被自动清空和删除,键值表将被重定向到参数指定的地址。如果传入的地址为0,则返回[假]。
注意:在没有理解[打包对象]和[解包对象]的特性时,请不要轻易用于正式项目,否则可能会导致程序不稳定(崩溃等)。
扩展方法
表单文本
生成表单文本
将键值表序列化为表单文本:
表单文本将被执行URL编码处理,可以通过参数[按主键正向排序]指定为真,输出为带排序的表单文本。
如果需要获取 URL编码前的内容,可以在外层加入[URL解码]函数恢复为无URL编码的内容。
.版本 2
.支持库 e2ee
.子程序 到表单文本
.局部变量 键值表, 存取键值表
键值表.创建 (“country”, “中国”, “name”, “JimStone”, “age”, 18, “cover”, “/images/icon/avatar1.gif”)
' // 生成URL编码过的表单文本
输出调试文本 (键值表.到表单文本 (#文本编码格式_UTF8, 真))
' // 生成未执行过URL编码的表单文本
输出调试文本 (URL解码 (键值表.到表单文本 (#文本编码格式_UTF8, 真), #文本编码格式_UTF8))
- age=18&country=%E4%B8%AD%E5%9B%BD&cover=%2Fimages%2Favatar1.gif&name=JimStone
- age=18&country=中国&cover=/images/avatar1.gif&name=JimStone
从表单文本加载
.版本 2
.支持库 e2ee
.子程序 加载表单
.局部变量 i, 整数型
.局部变量 编码, 文本型
.局部变量 表单文本, 文本型
.局部变量 表单项, 存取列表
.局部变量 键值表, 存取键值表
编码 = “UTF-8”
表单文本 = “age=18&country=%E4%B8%AD%E5%9B%BD&cover=%2Fimages%2Ficon%2Favatar1.gif&name=JimStone”
.计次循环首 (表单项.从文本分割 (表单文本, “&”, “=”, , , , ), i)
键值表.置文本 (URL解码 (表单项.取文本 (i, 1), 编码), URL解码 (表单项.取文本 (i, 2), 编码))
.计次循环尾 ()
输出调试文本 (键值表.到文本 ())
{
age: 18
country: 中国
cover: /images/icon/avatar1.gif
name: JimStone
}
主键更名
键值表.主键更名 更改键值表中的主键名称。原始名称的主键必须存在,目标名称主键不能存在,参数个数只能为复数,单数为原主键名称,复数为新主键名称。否则返回失败。
键值互换
键值表.键值互换 生成键值互换之后的键值表。新的键为原键值表的 取文本() 生成的内容,数值、日期、字节集等等会被转换为文本,如果同一个值作为主键同时存在多个键值,则只会保留最后一个结果(由于键值表的存储结构可能会造成结果的随机性)。
子列表排序
键值表.子列表排序 对键值表中的子列表进行排序。
子列表添加
键值表.子列表添加 对键值表中的子列表进行添加值的操作。其中主键指向的值类型必须为[存取列表]类型时才有效。
子列表删除
键值表.子列表删除 对键值表中的子列表进行删除操作。其中主键指向的值类型必须为[存取列表]类型时才有效。