存取列表
【E2EE文档】

存取列表

[存取列表]对象相当于数组。它可以通过索引快速的获取、添加和修改数据内容。

在以下内容中,将使用别名[列表]来表示[存取列表]。和[存取键值表]不同的是存取列表是有序的。数据的顺序和添加/加载的顺序是一致的。

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

列表做为比[数组]更便捷的替代品,由于其更加灵活和便捷,和[存取键值表]一样,已成为一种通用的逻辑解耦形式,被广泛应用在各种主流语言中。以下是列表在其它语言中的常见对象名称:

  • [Java] List(ArrayList)
  • [JavaScript] Array
  • [C#] List
  • [PHP] Array

支持的数据类型

列表的值支持以下类型的数据:

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

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

快速查看列表

要快速查看[列表]的内容,可以使用[到文本]方法,将列表快速输出为便于阅读的文本内容。

  • 列表.到文本

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

快速创建列表

有两种方式可以快速创建一个列表。

1. 通过 创建列表 函数创建

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

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

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

建议使用“列表.创建”方法

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

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

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

 

添加

类型添加

添加内容可以使用“添加”开头,后边带[类型]名称,进行添加值的操作。例如:列表.添加文本("JimStone")。

执行添加操作后,新的内容将被插入到[列表]的尾部。添加的作用类似于易语言的[加入成员]函数。

类型添加方法

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

示例

 

通用添加

您可以通过[列表.添加值]方法,直接将[通用型]内容添加到[列表]尾部。

注意:[列表.添加值] 方法只支持[支持的数据类型]枚举出来的数据类型(除了“宽文本型”),其它数据类型会直接返回失败。

示例

 

取值

[列表]的[位置索引]是从[1]开始的,这一点和[易语言]中的数组是一样的。

取值的方法以“”开头,后边带[类型]名称。例如:列表.取文本()

取值方法

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

示例

JimStone 18 2019年7月27日2时46分26秒 E2EE

赋值

类型赋值

[列表]l类型赋值方法以“”开头,后边带[类型]名称。

类型赋值方法

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

示例

通用赋值

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

  • 置值

示例

插入

插入方法的名称以“插入”开头,后边带[类型]名称。例如:列表.插入文本。

插入方法中的[索引]参数指向要插入的位置,为[1]则表示插入顶部,如果为负数从尾部插入

类型插入方法

  • 插入文本
  • 插入整数
  • 插入长整数
  • 插入小数
  • 插入双精度小数
  • 插入逻辑值
  • 插入时间
  • 插入字节集
  • 插入宽文本
  • 插入宽文本_编码
  • 插入列表
  • 插入键值表

通用插入方法

  • 插入值

示例

寻址表达式

[寻址表达式]的具体说明和使用方法,可以参考[存取键值表]中的说明,规则完全一致,只需要将取值或者赋值时的[索引]参数换成表达式即可。

[列表]的寻址必然是以“//[]”开头的。例如:”//[1]“,”//[1].名称“

快捷取值

[列表]支持[快捷取值]方式,取值时更加便捷。具体使用方法是根据数据从外到内的级别,按照顺序填写取值方法的参数。

示例

18 JimStone2 19 JimStone

常用方法

删除

删除[索引]参数位置的值。

清空

清空列表中的所有内容。

取类型

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

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

当[索引]不存在时通过“取类型”方法返回的是[]类型。

以下函数实现可以用来输出列表指定索引中的内容类型:

取数量

返回整个列表中内容的数量。

是否为空值

判断[索引]参数对应的值是否为空。[索引]超出范围时也返回为[]。

合并到

合并当前[列表]到指定[列表]尾部。合并后不会清空当前列表的数据。

序列化和反序列化

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

列表支持的序列化格式

  • JSON
  • 字节集
  • Base64
  • CSV
  • XLS(仅支持输出)
  • 数组
  • 格式文本

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

JSON

从JSON载入数据

  • 列表.从JSON载入

参数说明

[JSON数据] 要载入的JSON文本内容。支持 文本 和 字节集 类型的数据。如果JSON文本内容不为数组类型(Array)则载入失败。数组类型格式为“[”开头“]”结束,例如:[ "JimStone": "E2EE" ]。对象类型(Object)的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”后的内容,否则会载入失败。

CSV

列表支持CSV文件的加载和生成。

生成CSV

  • 列表.到CSV

参数说明

[是否输出表头] 是否输出表头(列名称)到首行。

[字段名称] 要输出的字段名列表,用于指定输出字段的顺序和内容。

  1. 当[是否输出表头]参数为[]时,[字段名称] 用于指定输出字段的顺序
  2. 当[是否输出表头]参数为[]时,[字段名称] 用于指定输出字段的顺序以及表头名称

[表头名称] 要实际输出的CSV表头名称列表。只有参数[是否输出表头]参数为[]时,才会用到此参数,如果此参数为空则输出[字段名称]为实际表头名称。表头名称将做为CSV文件的第一条记录输出。示例:假设数据内容为“[{ name: Jim, age: 18, sex: 女 }, { name: Stone, age: 28, sex: 男 }]”,此时您可以指定本[表头名称]参数为“[名称, 年龄, 性别]”,输出时第一条数据直接输出为“名称,年龄,性别”。当本[表头名称]参数的数量少于[字段名称]数量时,表头外的数据输出以[字段名称]为主。

载入CSV

  • 列表.从CSV载入

参数说明

[CSV内容] 要加载的CSV内容。

[内容包含表头] 内容中是否包含表头信息。如果不包含,则【表头】参数不能为空。

[表头] 要输入的CSV的表头格式。如果不为空,当参数【内容包含表头】为真时,回写表头名称到此变量,当参数【内容包含表头】为假时,则使用此变量的文本内容作为表头。表头格式示例:[列名1, 列名2,列名3]。

XLS

[列表]支持通过写入二进制文件的方式写出XLS文件,操作的电脑或服务器并不需要安装 Office 软件。

  • 列表.到XLS

使用方式基本跟[到CSV]一致。其中[生成格式]参数可以参照方法的说明设置,格式信息并不保证绝对有效。

由于E2EE并非专业的文档处理框架,所以目前并不包含载入XLS的功能。

数组

[列表]支持和易语言[数组]类型之间互相转换。方法如下:

  • 列表.从数组载入
  • 列表.到数组

数组序列化的方式是基于内存复制的(非地址引用),所以转换后可能会产生更多的内存空间,使用时请根据具体场景选择性使用。

当转换过程中遇到[支持的数据类型]之外的数据,将转换失败。

不支持[自定义数据类型]数组,如果您需要将[列表]和[自定义数据类型]数组之间互相转换,请使用从服务器获取的[对象映射中心]对象。

示例

数组:4{1,2,1,1} [1,2,1,1]

格式文本

[列表]可以通过指定[行文本]和[列文本]的方式,载入和生成指定格式文本。方法如下:

  • 列表.从文本分割
  • 列表.到表格文本

所谓[行文本]和[列文本],指的是行分隔文本和列分隔文本。

  • [[2,1,1,1],[1,2,1,1],[1,1,2,1],[1,1,1,2]]
  • 2-1-1-1 1-2-1-1 1-1-2-1 1-1-1-2
  • [[2,1,1,1],[1,2,1,1],[1,1,2,1],[1,1,1,2]]

由于E2EE并非专业的文档处理框架,所以目前并不包含载入XLS的功能。

从指定来源载入

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

  • JSON
  • 字节集
  • Base64

从文件载入

  • 列表.从文件载入

从指定文件加载列表。

从网络载入

  • 列表.从网络载入

从指定网址加载列表。成功返回[]。

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

文件同步

[列表可以通过绑定文件路径的方式,快速从文件载入和写入数据。通过[打开文件]绑定路径后,直接调用[保存文件]可直接将内容写入到打开的路径中。

相关方法

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

使用流程

1. 打开文件

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

2. 保存文件

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

内存处理

避免内存复制

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

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

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

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

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

  • 列表.打包对象
  • 列表.解包对象

打包对象

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

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

解包对象

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

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

扩展方法

过滤主键

过滤列表中的键值表的内容。只针对列表下级为键值表的内容做处理,主键名为 列表下的 键值表的主键名,允许 保留 和 排除 两种方式。

主键更名

更改列表中的键值表中的主键名称。只适用于列表嵌套键值表的情况。参数个数只能为复数,单数为原主键名称,复数为新主键名称。否则返回[]。

取子列表

获取列表的子集。通过指定起始位置和数量来获取子列表。

抽取表头

从列表数据中抽取表头数组。返回的数组内容为列表中第一项的[主键]。如果列表中第一项不为[存取键值表]则返回 []。

  • 数组:2{“名称”,“年龄”}

连接文本

将当前列表按照顺序转换成文本拼接起来,中间使用参数[连接字符]做连接。此功能等同于PHP中的 array().join() 功能。

示例

SELECT * FROM user WHERE id IN (1, 3, 5, 7, 9)

连接字节集

将当前列表按照顺序转换成字节集并进行拼接,中间使用参数[连接字符集]做连接。此功能等同于JavaScript或PHP中的 array.join() 功能。非字节集的数据会被写入为字节集,譬如 整数 值会被写入4字节的数据,文本则直接被写入(不包含尾部的\0),键值表和列表则会被序列化之后写入。用法跟 连接文本 差不多。

排序

对[列表]进行排序处理。

其中[排序方式]可以指定排序规则,支持以下常量:

  • #存取排序方式_按文本升序
  • #存取排序方式_按文本降序
  • #存取排序方式_按整数升序
  • #存取排序方式_按整数降序
  • #存取排序方式_按小数升序
  • #存取排序方式_按小数降序

示例

[ 1, 3, 5, 7, 9 ]

查询

筛选列表数据并且重新组织数据结果(类似于SQL中的“SELECT”语句)。使用时建议参考[存取查询器]对象说明。

以下简单说明以下几个重要参数。

[返回格式] 取回数据时的字段格式。功能跟 SQL 标准中的“Select”基本一致。如果为空、空文本 或 文本“*”则取回的数据为原始格式内容。您可以指定要返回的数据范围,通过“,”进行分割。支持所有“Where”函数中的【查询条件】表达式格式,可通过“AS”关键字指定返回字段的别名。例如:“name AS 名称, age AS 年龄, children”(返回 [name] 和 [age] 字段并重命名为“名称”和“年龄”,返回[children] 字段)。如果您想取回某个字段并直接替换当前整个列表行的内容,可以使用“$self”做为昵称,例如:“name AS $self” 意味着直接用“name”替换当前列表行本身,假设列表内容为:“[{name: 张三}, {name: 李四}, {name: 王五}]”,那么执行完这句后,结果为:“[张三, 李四, 王五]”。

[查询条件] 查询数据的条件表达式。功能跟SQL基本一致。支持以下命令:

  • 【文本】 单引号“'”包裹的内容。例如:'JimStone',支持单引号自转义,格式“'”,例如:'JimStone's'(最终文本为“JimStone's”)
  • 【数值运算】 +(可文本相加)、-、*、/、%(取余)
  • 【逻辑运算】 =、>、<、>=、<=、!=、==(绝对等:类型和值均相等)、!==(绝对不等)
  • 【且或】 AND、&&:且 OR、&&:或
  • 【LIKE】 用法和MySQL一样。%可以在头部或(和)尾部,例如:“name LIKE '%Stone'”(查询[name]中以“Stone”结尾的文本)。前后都为“%”则表示包含 支持“NOT LIKE”用法,例如:“name NOT LIKE '%Stone%'”(查询[name]中不包含“Stone”的数
  • 【IN】在范围内: 可以通过中括号“[]”来指定数据范围。例如:“name IN ['Jim', 'Stone']”(查询[name]为“Jim”或者“Stone”的数据)。“age IN [12, 18, 16]”(查询[age]为12、18或16的数据) 支持“NOT IN”用法,例如:“age NOT IN 12, 13
  • 【优先级】使用小括号“()”指定运算优先级: (age % 3) * 2 = 4 name = 'E2EE' or (name = '1211' AND age = 18)
  • 【常数运算】 4 * 3 % 5 + 2
  • 【占位符】使用大括号“{}”指定参数变量: 格式:大括号+数字,例如:{1} 指向当前方法的第一个【表达式参数】内容 尾部带 u 表示宽文本,例如:{2u} 指第二个【表达式参数】为宽文本(不写u表示普通文本或指向原数据) 尾部带 c 表示复制内容,通常用于【表达式参数】为“创建列表()”函数动态定义的【存取列表】类型参数,例如:{2c} 指向第二个【表达式参数】,使用前进行复制(避免被易语言回收)

示例

  • ==== 筛选出年龄大于18岁的 ====

  • ==== 提取所有的名称 ====