This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
api:transforms:zh [2023/10/20 09:36] hfsr [Transforms(变换) API] |
api:transforms:zh [2023/12/01 07:52] (current) hfsr [Transforms(变换) API] |
||
---|---|---|---|
Line 1: | Line 1: | ||
Transforms(变换) | Transforms(变换) | ||
================= | ================= | ||
- | transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器,这些迭代器是 `text` 与 `sh` 命令解析的核心。 | + | transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器,这些迭代器是`text`与`sh`命令解析的核心。 |
===== Transforms(变换) API ===== | ===== Transforms(变换) API ===== | ||
- | * **Transforms工作于_序列_之上** | + | * **Transforms工作于序列之上** |
+ | 所有transform方法都预期在序列上迭代,参见https://www.lua.org/manual/5.2/manual.html#3.4.6。 | ||
+ | \\ | ||
+ | * **first 与 last** | ||
+ | 此API中所有的`first`和`last`参数均与`string`方法(例如`string.sub`)中的`first`与`last`参数工作方式一致。也就是可以接收负值,负值为从后向前数。`first`(当选择时)默认相当于 1,而 `last` 默认相当于 -1。 | ||
+ | \\ | ||
+ | * **判断函数(predicate)** | ||
+ | 译者注:此处的predicate通用的译名是“谓词”,指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名,不利于理解。因此译为“判断函数”。 | ||
+ | 所有接收判断函数的transform方法均使用以下的判断函数定义: | ||
+ | \\ | ||
+ | * `predicate(element: value, index: number, tbl: table): number, number` | ||
+ | 此判断函数会在`tbl`的每个索引值上依次调用。`element`为`tbl[index]`的值。 | ||
+ | 通常而言,判断函数将会忽略`index`与`tbl`,仅处理`element`。但一些判断函数可能会需要检查`tbl`中在`index`之前或之后的值。 | ||
+ | **应注意**,传递给判断函数的`tbl`实际上只是传递给transform api的原始表的一个**视图(view)**。此处的**视图**不是原生的序列,而是只有`tbl`中[`first`, `last`]范围内的值。 | ||
+ | \\ | ||
+ | 换言之,判断函数处理“一组元素”,并返回代表所满足条件的值。 | ||
- | 所有的transform方法都预期在序列上迭代,参见https://www.lua.org/manual/5.2/manual.html#3.4.6 | + | * **元素组** |
+ | "元素组"一词代指下列之一: | ||
+ | A)传递给判断函数的单个`element`。与`tbl[index]`的值为同一个。 | ||
+ | 或者 | ||
+ | B)`tbl`中自`index`起的元素序列。判断函数可能会从`index`处开始迭代,数量为其需要检查的元素数,直到`#tbl`为止。 | ||
+ | \\ | ||
+ | * **返回值** | ||
+ | 返回值的可能情况: | ||
+ | 参数1:若为`false` 或 `nil`,代表这组元素不满足判断函数的条件。若为`index`,代表满足条件。函数应当直接返回给定函数的索引号,也就是元素组的起始元素索引号。 | ||
+ | 参数2:满足判断函数的元素组大小,或`nil`。 | ||
+ | 一些tranform方法可能会将第二个参数指定为可选,例如`transforms.first()`。 | ||
+ | \\ | ||
+ | 一些transform方法可能会指定其他类型的判断类型,例如表或字符串。这些判断函数的用法特定于对应的方法,且在此处详细列出的方法中定义。 | ||
- | * **first 与 last** | + | ==== 方法 ==== |
- | 此API所有的 `first` 与 `last` 参数均与`string`方法(例如`string.sub`)中的 `first` 与 `last` 参数工作方式一致。因此可以接收负值,负值为从后向前数。`first`(当选择时)默认相当于 1,而 `last` 默认相当于 -1。 | + | * `transforms.sub(tbl: table, first: number, last: number or nil): table` |
- | + | 与`string.sub`作用类似,返回`tbl`从`first`到`last`的子表。 | |
- | * **判断函数(predicate,谓词)** | + | \\ |
- | + | * `transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number` | |
- | 译者注:此处的predicate通用的译名是“谓词”,指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名,不利于理解。因此译为“判断函数”。 | + | 返回`tbl`中(范围在`first`与`last`索引值之间,包含首尾)满足`predicate`的首个元素的索引值。第二个返回值为连续匹配的元素最后一个的索引值。一般而言会返回两个同样的值,即匹配的连续元素为1个。`predicate`可以返回第二个返回值(可选),代表匹配的连续元素序列长度。 |
- | + | \\ | |
- | 所有接收判断函数的transform方法均使用以下定义: | + | 当`predicate`为表时,`transforms.first()`将会返回`tbl`中首个满足条件的子表的首尾索引值,这种情况下的匹配指匹配`predicate`表中的任一元素。 |
- | + | \\ | |
- | * `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方法可能会指定其他可用的判断数据类型,例如表或字符串。这些判断函数的用法特定于对应的方法,且在此处详细列出的方法中定义。 | + | |
- | + | ||
- | ==== Methods ==== | + | |
- | + | ||
- | * `transforms.sub(tbl: table, first: number, last: number or nil): table` | + | |
- | + | ||
- | Behaves similarly to `string.sub`. Returns a sub table of `tbl` from `first` to `last`. | + | |
- | + | ||
- | * `transforms.first(tbl: table, predicate: function or table, first: number or nil, last: number or nil): number, number` | + | |
- | + | ||
- | Returns the first index in `tbl` (between indexes `first` and `last`, inclusively) where `predicate` is satisfied. The 2nd return is also the ending index of the match. General examples will have the same two values returned, i.e. a match of length 1. The `predicate` can (optionally) return a 2nd return value to indicate the size of the match. | + | |
- | + | ||
- | In the case that `predicate` is a table, `transforms.first()` returns the starting and ending index of the first matching sub table in `tbl` that matches ANY one of the tables in `predicate`. | + | |
- | + | ||
- | Examples: | + | |
```lua | ```lua | ||
Line 79: | Line 63: | ||
``` | ``` | ||
- | Output | + | 输出: |
``` | ``` | ||
4 5 | 4 5 | ||
Line 89: | Line 73: | ||
``` | ``` | ||
- | Output | + | 输出 |
``` | ``` | ||
3 5 | 3 5 | ||
``` | ``` | ||
- | * `transforms.partition(tbl: table, partioner: function, first: number or nil, last: number or nil): table of tables` | + | * `transforms.partition(tbl: table, partioner: function, first: number or nil, last: number or nil): table of tables` |
- | + | 返回一个子表的列表,子表来自`tbl`,由`partioner`生成,来源范围为从`first`到`last`。`partioner`为判断函数,定义见前文。 | |
- | Returns a list of sub lists from `tbl`, generated by `partioner` within the range from `first` to `last`. `partioner` is a `predicate` function, defined above. | + | \\ |
- | + | 传递给`partitioner`的`index`参数将会跳过子表的范围,即此参数会增加`n`,`n`即为分区大小。 | |
- | The `index` parameter passed to the `partitioner` will skip ranges, i.e. it will increase by `n` where `n` is the size of the partition. | + | \\ |
- | + | 此方法的`partitioner`判断函数必须同时返回匹配的元素组的开始与结束索引。请再次参见前文的`predicate`相关信息。 | |
- | The `partitioner` predicate for this method must return the starting AND ending index of satisfied element sets. Again, see the `predicate` info above. | + | \\ |
- | + | * `transforms.begins(tbl: table, sub: table, first: number or nil, last: number or nil)` | |
- | * `transforms.begins(tbl: table, sub: table, first: number or nil, last: number or nil)` | + | 若`tbl`从`first`到`last`的子表能完全组成`v`(自首个元素对齐),则返回`true`。`first`与`last`元素可以正确处理负数。上文描述也就是说: |
- | + | `v[1] == tbl[first + 0]` | |
- | Returns true if the subset of `tbl` from `first` to `last` fully composes `v` aligned at the first index. Assuming `first` and `last` have been adjusted for negative wrap around, that is to say: | + | `v[2] == tbl[first + 1]` |
- | + | ... | |
- | `v[1] == tbl[first + 0]` | + | `v[#v] == tbl[first + #v - 1]` |
- | + | \\ | |
- | `v[2] == tbl[first + 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`则会被忽略,不会被加入结果。 | |
- | `v[#v] == tbl[first + #v - 1]` | + | `adapter`函数遵循判断函数的格式,除了返回值处理方面。 |
- | + | * **Adapter函数返回值** | |
- | + | 简单的情况是返回单个值,例如`tx.foreach({'a', 'b', 'c'}, string.upper)`将会返回`{'A', 'B', 'C'}`。 | |
- | Where `first + #v - 1` is within the bounds of `[first, last]` of `tbl`. | + | 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}` | |
- | * `transforms.foreach(tbl: table, adapter: function, first: number or nil, last: number or nil)` | + | |
- | + | ||
- | Returns an adaptation of each element in `tbl` from `first` to `last`. Any `nil` result of the `adapter` is ignored, and not appended to the result. | + | |
- | + | ||
- | The `adapter` follows the `predicate` signature except for the handling of the return values | + | |
- | + | ||
- | * **Adapter Returns** | + | |
- | + | ||
- | The simple case is to return a single value. E.g. `tx.foreach({'a', 'b', 'c'}, string.upper)` would return `{'A', 'B', 'C'}`. | + | |
- | + | ||
- | The adapter can return `nil` to skip a value. E.g. `tx.foreach({'1', 'foobar', '2'}, function(n) return tonumber(n) end)` would return `{1, 2}`. | + | |
- | + | ||
- | But the `adapter` can return a second value that is used in place of the next sequence number. E.g. `tx.foreach({'1','foobar','3'},function(n,i) return tonumber(n), tostring(i) end)` would return `{["1"]=1, ["3"]=3}` | + | |