transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器,这些迭代器是 text
与 sh
命令解析的核心。
所有的transform方法都预期在序列上迭代,参见https://www.lua.org/manual/5.2/manual.html#3.4.6
此API所有的 first
与 last
参数均与string
方法(例如string.sub
)中的 first
与 last
参数工作方式一致。因此可以接收负值,负值为从后向前数。first
(当选择时)默认相当于 1,而 last
默认相当于 -1。
译者注:此处的predicate通用的译名是“谓词”,指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名,不利于理解。因此译为“判断函数”。
所有接收判断函数的transform方法均使用以下定义:
predicate(element: value, index: number, tbl: table): number, number
此判断函数会在 tbl
的每个索引上依次调用。 element
为 tbl[index]
中的值。通常而言,判断函数将会忽略 index
与 tbl
,仅处理element
。但一些判断函数可能会需要检查tbl
中在index
之前或之后的值。(重要!)应注意,传递给判断函数的tbl
实际上只是传递给transform api的原始表的一个视图(view)。此处的视图(view)不是原生的序列,而是只会返回tbl
中 [first
, last
] 范围内的值。
换言之,判断函数处理一个“元素组”,并返回代表满足的条件的值。
“元素组”一词代指下列之一:
A)传递给判断函数的单个element
。与tbl[index]
的值为同一个。
或者
B)tbl
中自index
起的元素序列。判断函数可能会从index
处开始迭代,数量为其需要检查的元素数,直到 #tbl
为止。
返回值的可能情况:
参数1:若为false
或 nil
,代表元素组不满足判断函数的条件。
若为index
,代表满足条件。函数应当直接返回给定函数的索引号,也就是元素组的起始元素索引号。
参数2:满足判断函数的元素组大小,或nil
。
一些tranform方法可能会将第二个参数指定为可选,例如transforms.first()
。
一些transform方法可能会指定其他可用的判断数据类型,例如表或字符串。这些判断函数的用法特定于对应的方法,且在此处详细列出的方法中定义。
transforms.sub(tbl: table, first: number, last: number or nil): table
与 string.sub
作用类似,返回tbl
从first
到last
的子表。
transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number
返回tbl
中(范围在first
与last
索引之间,包含首尾)满足predicate
的首个元素的索引。第二个返回值为最后一个连续匹配的元素索引。一般而言会返回两个同样的值,即匹配的连续元素为1个。predicate
可以返回第二个返回值(可选),代表匹配的连续元素序列长度。
当predicate
为表时,transforms.first()
将会返回tbl
中首个满足条件的子表的首尾索引值,这种情况下的匹配指匹配predicate
表中的任一元素。
样例:
local tx = require("transforms") print( tx.first ( { 1, 1, 3, 2, 4, 7 }, function(e, i, tbl) local evens = 0 for i=i,#tbl do if tbl[i] % 2 == 0 then evens = evens + 1 else break end end return evens > 0, evens end))
输出:
4 5
local tx = require("transforms") print( tx.first ( { 1, 1, 3, 2, 4, 7 }, { {1, 2}, {3, 2, 4} }) )
输出
3 5
transforms.partition(tbl: table, partioner: function, first: number or nil, last: number or nil): table of tables
返回一个子表的列表,子表来自tbl
,由partioner
生成,范围为从first
到last
。partioner
为判断函数,定义见前文。
传递给partitioner
的index
参数将会跳过范围,即此参数会增加n
,n
即为分区大小。
此方法的partitioner
判断函数必须同时返回匹配的元素组的开始与结束索引。请再次参见前文的predicate
相关信息。
transforms.begins(tbl: table, sub: table, first: number or nil, last: number or nil)
若tbl
从first
到last
的子表完全组成了sub
(自首个元素对齐),则返回true
。first
与last
元素可以正确处理负数。上面的表达也就是说:
v[1] == tbl[first + 0]
v[2] == tbl[first + 1]
…
v[#v] == tbl[first + #v - 1]
此处的first + #v - 1
在tbl
的[first, last]
范围内。.
transforms.foreach(tbl: table, adapter: function, first: number or nil, last: number or nil)
返回tbl
中从first
到last
的每个元素的修改版本。若adapter
的结果出现nil
则会被忽略,不会被加入结果。
adapter
函数遵循判断函数的格式,除了返回值处理方面
简单的情况是返回单个值,例如tx.foreach({'a', 'b', 'c'}, string.upper)
将会返回{'A', 'B', 'C'}
。
adapter函数可以通过返回nil
来跳过某个值。例如,tx.foreach({'1', 'foobar', '2'}, function(n) return tonumber(n) end)
将会返回{1, 2}
。
adapter
函数可以返回第二个值,此值会被用于序号(返回结果键值)。例如tx.foreach({'1','foobar','3'},function(n,i) return tonumber(n), tostring(i) end)
将会返回{["1"]=1, ["3"]=3}