builtin.string 库模块帮助文档

string 成员列表 #

string.cmpMatch( ,"字符串参数" ) #

使用完全匹配比较字符串，忽略大小写，相同返回 true。
否则使用模式匹配搜索子串，忽略大小写，找到返回 true。
改用 string.indexOf 函数可禁用模式匹配查找子串。

string.concatUtf16(str,...) #

将所有参数转换为 UTF-16 字符串并连接后返回。
参数可以是数值，字符串，UTF-16 编码字符串。
忽略 null 值参数

string.crlf(字符串,回车换行,合并空行数) #

自动调用 tostring 函数转换传入参数 @1 为字符串。
此函数格式化参数 @1 的回车换行或单独的回车换行符为参数 @2 指定的换行标记。
参数 @2 默认为 '\x0D\x0A' ，如果改为为 '\x0A' 则格式化为单个换行符。
可选用参数 @3 指定合并空行后保留的最大空行数（单换行不是空行），省略则不合并。

注意字符串字面值解析换行的规则:
双引号或反引号内字符串只有换行没有回车,
单引号内字符串解析时忽略所有回车换行,
使用/块注释/包含字符串则总是将换行规范解析为回车换行组合

string.each #

创建适用于 for in 语句的迭代器，
用于在文本中逐行搜索匹配单行文本，支持模式匹配语法。

此函数与 string.gmatch 相似，
每次循环都会返回匹配的字符串（多个捕获分组则返回多个迭代变量）。
但 string.each 的匹配目标是单行文本（拆分为多行后逐行匹配），
例如模式 ^ 或 $ 在此函数里匹配行首与行尾。

可将返回迭代器作为 table.array 的参数以生成数组

string.each(字符串,模式串,行分隔符) #

必须使用参数 @2 指定模式表达式（每次的匹配目标都是单个文本行）。
迭代变量为匹配的字符串，如果有捕获分组则迭代变量的个数等于捕获组的个数。

参数 @3（行分隔符）也支持模式匹配语法,省略则默认匹配回车换行或单个换行与回车。

string.eachChar(字符串) #

创建一个遍历文本中所有字符的迭代器，迭代器可用于 for in 语句。
调用 string.gmatch 并将模式串参数指定为 :|. 也可以遍历所有字符。
或者不指定参数调用 string.split 函数可将字符串拆分为字符串（单字符）数组。

string.escapePattern(pattern, ignoreCase) #

转义参数 @pattern 指定的模式串用于模式匹配原始字符串。
参数 @ignoreCase 为 true 则直接将模式串前放入 <@@...@> 内部以禁用模式语义并忽略大小写。
模式串首字符不为 @ 时则放入 <@...@> 内部以单纯禁用模式语义。
模式串首字符为 @则在所有标点符号前增加模式转义符（反斜杆）。
返回值可与其他模式串拼接以实现局部禁用模式语义。

如果模式串为字面值建议在模块串开始或非捕获组首尾中直接使用 @ 符号禁用模式语义。
如果仅仅是查找原始字符串（区分大小写）可改用 string.indexOf 或 raw.indexOf 函数。

string.expand #

重复替换直到找不到匹配,
可用于展开字符串中的环境变量

string.expand(字符串,查找模式串,替换函数) #

在字符串中重复执行替换操作,
直到参数@2指定的模式串找不到匹配,
省略参数@2,@3则默认展开百分号包含的进程环境变量
可用于展开文件路径中的环境变量
注意即使替换函数返回null,此函数仍然会替换为空串,
如果替换结果为空字符串,此函数返回 null

string.getenv("变量名") #

读取当前进程环境变量
成功返回字符串,失败返回 null

string.gfind(字符串,模式串,开始位置) #

for i,j,group1 in string.gfind( /*查找字符串*/,"(.)") { 

}

string.isUtf8() #

快速检测字符串是否包含UTF8编码
空字符串返回null

string.lines #

创建用于for in 语句的迭代器按行拆分字符串。
可用模式串自定义行分隔符，此函数与 string.splitEx 函数使用相同的拆分规则。

可将返回迭代器传入 table.array 生成数组。
按行读取文件请使用 io.lines 函数。

string.lines(字符串,行分隔符,列分隔符,最大列数) #

按行拆分参数 @1 传入的字符串，传入 null 或空串字符串忽略不操作。
可选用参数 @2 自定义行分隔符，支持模式匹配语法。
可选用参数 @3 自定义列分隔符，支持模式匹配语法。

所有分隔符模式串可用括号创建捕获组，首个捕获组如下处理：

• 模式串尾部有 $ 符号，则捕获组放到上个拆分结果尾部。
  
• 模式串头部有 ^ 符号，则捕获组放到下个拆分结果头部。
  
• 模式串头部有^ 符号尾部有 $ 号则捕获组本身拆分为一个单位。
  如果返回行分隔符，则迭代器的第 2 个循环变量为 true。
  

可选用参数 @4 限定最大拆分列数目。

如果不指定列分隔符则循环返回字符串，否则返回列数组。

string.loadcode #

加载并执行 aardio 代码或文件,返回 HTML 模板输出的 HTML 代码
如果当前应用未定义 response 对象,请使用 print 函数替代。
此函数也可以用于非 HTML 格式的任意字符串模板，
但非 HTML 格式的字符串开始部分必须是 aardio 模板标记

string.loadcode("代码文件",...) #

加载并执行 aardio 代码或文件,
返回 HTML 模板输出的 HTML 代码,失败返回空值,错误信息。
参数@1,与 loadcode 函数相同,其他参数作为模板参数传给被调用的文件,
在被调用文件的函数外部可使用 owner 参数获取首个模板参数,
也可以使用...获取多个模板参数

string.map #

搜索并返回搜索结果数组,
并调用映射函数转换数组中的每个匹配结果为新的值,

注意如果模式串中使用括号指定了多个分组,
映射函数会有多个对应的回调参数

string.map(字符串,模式,映射函数) #

参数@1指定要查找的字符串,
参数@2可以指定模式串,或包含多个表达式的数组,
省略则默认为[-\d]+,并且参数@3的默认值会被更换为tonumber
可选用参数@3指定映射函数,

返回值为匹配的字符串数组,如果有多个捕获分组则返回二维数组
如果参数@2不是数组而是表,则返回相同结构的表,
每个键对应的值更新为参数表中同名键指定的模式串的匹配结果。

string.matches("字符串","模式串") #

全局匹配并将匹配结果返回为数组
每次匹配成功的多个返回值存为成员数组
即使没有匹配到任何结果,也会返回一个空数组

string.reduce #

连续匹配多个模式串参数，对上一个匹配的首个返回值继续应用下一个模式串参数进行匹配。
逐步完成任务并返回最终匹配结果。

这个函数可以将复杂的模式匹配分为更简单的多个匹配步骤，
并可将 %() 这样无法拆分的对称匹配再次拆分并应用新的模式串进行局部匹配。

string.reduce(字符串,模式,...) #

参数 @1 指定要查找的字符串。
参数 @2 开始指定一个或多个模式串。
使用前一个模式串的首个匹配结果作为后面一次匹配的条件，
逐步缩减并返回最终匹配结果。
也可以在参数 @2 中使用一个数组指定多个模式串。

string.reduceReplace #

连续匹配多个模式串参数，
对上一个匹配的首个返回值继续应用下一个模式串参数进行匹配。
然后替换最后匹配的字符串。

这个函数可以将复杂的模式匹配分为更简单的多个匹配步骤，
并可将 %() 这样无法拆分的对称匹配进一步细分并应用新的模式串进行局部匹配，
并用最后一个参数指定的“替换对象”替换最终匹配的部分。

函数返回 2 个值：替换后的字符串，全部模式串匹配成功并执行替换的次数。
注意即使替换函数返回 null 值（取消替换）不会减少返回的替换计数。

string.reduceReplace(源字符串,模式串1,...模式串n,替换对象) #

对参数 @1 指定的源字符串进行替换。
可指定 1 个或多个模式串参数，对上一个模式匹配的首个结果应用下一个模式串参数匹配。
如果上个模式串指定了捕获组，则丢弃首个捕获组之外的部分继续匹配下个模式串。
如果任何一步匹配失败则返回参数 @1 指定的原始字符串（不作成功）。
如果最后一步匹配成功，则将全部匹配内容替换为最后一个参数指定的替换对象。

替换对象支持 string.replace 支持的字符串、函数、表等替换对象，
替换对象的规则也是相同的，具体请查看该函数说明。
可通过替换对象返回多个捕获组，请参考 string.replace 函数说明。

string.removeBom(字符串) #

如果字符串开始为UTF8 BOM，则返回移除该 BOM 的字符串。
如果字符串开始为 UTF-16 BOM,则移除 BOM 并返回转换为 UTF-8 编码的字符串,
否则直接返回参数

string.replaceUnmatched #

在一个或多个与指定模式不匹配的部分进行替换

string.replaceUnmatched(源字符串,替换模式串,替换对象,排除模式串1,排除模式串2...) #

在源字符串中保留与一个或多个排除模式串匹配的部分，
然后对剩余的部分进行单独替换。

"替换模式串","替换对象"等参数与 string.replace 函数要求一致，
"替换对象"可以是新的字符串、替换表或替换函数。
可以指定一个或任意多个"排除模式串"。
函数返回替换后的字符串与替换次数。

string.repline #

按行替换字符串,返回替换后的字符串,
此函数仅返回替换后的新字符串,只有一个返回值

string.repline(源字符串,模式串,替换串,替换次数) #

模式串用于匹配所有的单行文本,
替换串与 string.replace 用法相同
替换次数指的也是每一行内部进行替换的最大次数,不指定则不限制

string.repline(源字符串,模式串,替换函数,替换次数) #

模式串用于匹配所有的单行文本,
替换函数与 string.replace 用法相同
,
替换次数指的也是每一行内部进行替换的最大次数,不指定则不限制

string.repline(源字符串,模式串,替换表,替换次数) #

模式串用于匹配所有的单行文本,
替换表与 string.replace 用法相同
,
替换次数指的也是每一行内部进行替换的最大次数,不指定则不限制

string.saveFiles(dir,fileMap) #

批量保存文件（如果父目录不存在则自动创建父目录），
返回成功保存的文件数目。

参数 @dir 指定目标目录,
参数 @fileMap 指定一个映射表,键为文件名,值为要保存的文件数据。

string.search(array,str,pattern...) #

搜索 @str 指定的字符串并执行多步模式匹配。
函数会依次匹配所有模式串，上个匹配结果作为下一个匹配的源字符串，
或者作为调用下一个筛选器的参数（指定多个捕获组则有多个回调参数）。
最后一个模式串的全部匹配结果将添加到数组 @array，然后返回该数组。

关于模式串与筛选器参数请参考 string.search(receiver,str,pattern...)

string.search(receiver,str,pattern...) #

搜索 @str 指定的字符串并执行多步模式匹配。
可指定一个或多个模式串或筛选器参数。
函数会依次匹配所有模式串，上个匹配结果作为下一个匹配的源字符串，
或者作为调用下一个筛选器的参数（指定多个捕获组则有多个回调参数）。
如是上个模式串指定了捕获组则下个源字符串或筛选器的首个回调参数是首个捕获组。

可以使用函数或 lambda 表达式指定筛选器。
筛选器可以返回新的字符串，返回非字符串则表示是否保留上个模式串的匹配结果。

每一个模式串都执行全局搜索并返回全部匹配结果。
最后一个模式串的所有匹配结果将作为循环回调 @receiver 的参数。

参数 @receiver 指定函数则无返回值。

string.search(str,pattern...) #

搜索 @str 指定的字符串并执行多步模式匹配。
函数会依次匹配所有模式串，上个匹配结果作为下一个匹配的源字符串，
或者作为调用下一个筛选器的参数（指定多个捕获组则有多个回调参数）。
最后一个模式串的全部匹配结果将添加到一个新数组，然后返回该数组。

关于模式串与筛选器参数请参考 string.search(receiver,str,pattern...)

string.setenv("变量名","变量值") #

设置当前进程环境变量
参数@2为 null 或省略则删除参数@1指定的环境变量

string.splitEx #

使用模式匹配语法拆分字符串，返回拆分后的字符串数组。
此函数与 string.lines 迭代器使用相同的拆分规则。

string.splitEx(字符串,分隔符模式串,最大拆分次数,开始位置) #

使用模式匹配语法拆分字符串，返回拆分后的字符串数组。
参数 @1 传入 null 值或空字符串返回空数组。

分隔符模式串可用括号创建捕获组，首个捕获组如下处理：

• 模式串尾部有 $ 符号，则捕获组放到上个拆分结果尾部。
  
• 模式串头部有 ^ 符号，则捕获组放到下个拆分结果头部。
  
• 模式串头部有^ 符号尾部有 $ 号则捕获组本身添加到返回数组中。
  

省略分隔符模式则按行拆分，
兼容回车、换行、回车换行等不同换行风格，空行不合并。

最大拆分次数可省略（不限次数），分隔符单独加入拆分结果时拆分次数会对齐为奇数。
开始位置以字节为单位，省略则默认从开始拆分。

string.table #

解析以行为单位的字符串属性表。
类似功能的 string.list 支持用引号包含跨行的字段值，
但 string.table 仅将引号作为字面值处理。

string.table(字符串,键值分隔模式,行分隔模式,启用内联注释) #

解析以行为单位的字符串属性表。
除参数@1 以外其他所有参数都可以省略。
键值分隔模式默认为 "\s[:=]\s"，也就是忽略前后空白的冒号或等号。
行分隔符默认兼容回车换行、换行、单回车等行分隔符。
忽略以 # 或 ; 号开始的行。
启用内联注释则忽略键值对后空格加 # 或 ; 号引导的注释

自动完成常量

_CP_ACP=0
_CP_UTF16_BE=1201
_CP_UTF16_LE=1200
_CP_UTF8=65001

Markdown 格式