imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li

2026-08-24T08:08:27Z

Imported from legacy OpenComputers documentation at ocdoc.cil.li

New page

= Transforms(变换) =

transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是`text`与`sh`命令解析的核心。

== Transforms(变换) API ==

* '''Transforms工作于序列之上'''

<pre>所有transform方法都预期在序列上迭代，参见https://www.lua.org/manual/5.2/manual.html#3.4.6。
</pre>

* '''first 与 last'''

<pre>此API中所有的`first`和`last`参数均与`string`方法（例如`string.sub`）中的`first`与`last`参数工作方式一致。也就是可以接收负值，负值为从后向前数。`first`（当选择时）默认相当于 1，而 `last` 默认相当于 -1。
</pre>

* '''判断函数（predicate）'''

<pre>译者注：此处的predicate通用的译名是“谓词”，指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名，不利于理解。因此译为“判断函数”。
所有接收判断函数的transform方法均使用以下的判断函数定义：
</pre>

* `predicate(element: value, index: number, tbl: table): number, number`

<pre>此判断函数会在`tbl`的每个索引值上依次调用。`element`为`tbl[index]`的值。
通常而言，判断函数将会忽略`index`与`tbl`，仅处理`element`。但一些判断函数可能会需要检查`tbl`中在`index`之前或之后的值。
</pre>
'''应注意'''，传递给判断函数的`tbl`实际上只是传递给transform api的原始表的一个'''视图（view）'''。此处的'''视图'''不是原生的序列，而是只有`tbl`中[`first`, `last`]范围内的值。
换言之，判断函数处理“一组元素”，并返回代表所满足条件的值。

<pre> * **元素组**
"元素组"一词代指下列之一：
A)传递给判断函数的单个`element`。与`tbl[index]`的值为同一个。
或者
B)`tbl`中自`index`起的元素序列。判断函数可能会从`index`处开始迭代，数量为其需要检查的元素数，直到`#tbl`为止。
</pre>

* '''返回值'''

<pre> 返回值的可能情况：
参数1：若为`false` 或 `nil`，代表这组元素不满足判断函数的条件。若为`index`，代表满足条件。函数应当直接返回给定函数的索引号，也就是元素组的起始元素索引号。
参数2：满足判断函数的元素组大小，或`nil`。
一些tranform方法可能会将第二个参数指定为可选，例如`transforms.first()`。
</pre>

一些transform方法可能会指定其他类型的判断类型，例如表或字符串。这些判断函数的用法特定于对应的方法，且在此处详细列出的方法中定义。

=== 方法 ===

* `transforms.sub(tbl: table, first: number, last: number or nil): table`

<pre>与`string.sub`作用类似，返回`tbl`从`first`到`last`的子表。
</pre>

* `transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number`

<pre>返回`tbl`中（范围在`first`与`last`索引值之间，包含首尾）满足`predicate`的首个元素的索引值。第二个返回值为连续匹配的元素最后一个的索引值。一般而言会返回两个同样的值，即匹配的连续元素为1个。`predicate`可以返回第二个返回值（可选），代表匹配的连续元素序列长度。
</pre>

当`predicate`为表时，`transforms.first()`将会返回`tbl`中首个满足条件的子表的首尾索引值，这种情况下的匹配指匹配`predicate`表中的任一元素。
样例：

```lua

local tx = require("transforms") print( tx.first ( { 1, 1, 3, 2, 4, 7 }, function(e, i, tbl)

<pre>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
</pre>
end)) ```

输出： ``` 4 5 ```

```lua 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`

<pre>返回一个子表的列表，子表来自`tbl`，由`partioner`生成，来源范围为从`first`到`last`。`partioner`为判断函数，定义见前文。
</pre>

传递给`partitioner`的`index`参数将会跳过子表的范围，即此参数会增加`n`，`n`即为分区大小。
此方法的`partitioner`判断函数必须同时返回匹配的元素组的开始与结束索引。请再次参见前文的`predicate`相关信息。
* `transforms.begins(tbl: table, sub: table, first: number or nil, last: number or nil)`

<pre>若`tbl`从`first`到`last`的子表能完全组成`v`（自首个元素对齐），则返回`true`。`first`与`last`元素可以正确处理负数。上文描述也就是说：
`v[1] == tbl[first + 0]`
`v[2] == tbl[first + 1]`
...
`v[#v] == tbl[first + #v - 1]`
</pre>

此处的`first + #v - 1`在`tbl`的`[first, last]`范围内。
* `transforms.foreach(tbl: table, adapter: function, first: number or nil, last: number or nil)`

<pre>返回`tbl`中从`first`到`last`的每个元素的修改版本。若`adapter`的结果出现`nil`则会被忽略，不会被加入结果。
`adapter`函数遵循判断函数的格式，除了返回值处理方面。
* **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}`
</pre>
== 目录 ==

{{:API/contents/zh}}

API/transforms/zh - Revision history

imported>OCDoc Import: Imported from legacy OpenComputers documentation at ocdoc.cil.li