Differences

This shows you the differences between two versions of the page.

--- api:transforms:zh [2023/10/20 08:49]
hfsr [Transforms]
+++ api:transforms:zh [2023/12/01 07:23]
hfsr [Transforms(变换) API]
@@ Line 1: / Line 1: @@
-Transforms(变换) API
+Transforms(变换)
 =================
-transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是 `text` 与 `sh` 命令解析的核心。
+transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是`text`与`sh`命令解析的核心。
-===== Transforms API =====
+===== Transforms(变换) API =====
-* **Transforms work on _sequences_**
+* **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`]范围内的值。
+\\
+  换言之，判断函数处理“一组元素”，并返回代表所满足条件的值。
-    All transforms methods expect to iterate over sequences, see 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 and last**
+==== 方法 ====
-    All `first` and `last` arguments act in the same fashion as the `first` and `last` arguments used in `string` methods such as `string.sub`. That is, it accepts negative values, which work relative from the end. `first` (when optional) defaults to 1, and `last` defaults to -1.
-* **The Predicate**
-    All transform methods that take a predicate use this predicate defintiion:
-  *  `predicate(element: value, index: number, tbl: table): number, number`
-  This predicate is called in sequence on each index in `tbl`. `element` is the value at `tbl[index]`. Generally, predicate methods ignore `index` and `tbl`, and only process `element`. But some predicates may need to check values in `tbl` before or after `index`. **Important** to note that the `tbl` passed to the `predicate` is actually a _**view**_ of the original table passed to the transforms api. This _**view**_ is not a natural sequence but instead only returns values from `tbl` within the [`first`, `last`] range.
-  In other words, the predicate handles a "set of elements" and returns parameters indicating the satisfied condition.
-    * **Set of Elements**
-    The "set of elements" refers to either:
-    A) The single `element` passed to the predicate. This is the same value at `tbl[index]`
-    or
-    B) The sequence of elements starting at `index` in `tbl`. The predicate may iterate from `index` for as many elements it needs to check, until `#tbl`
-    * **Return Parameters**
-    Possible values for the return parameters
-        `false` or `nil` if the predicate is not satisfied with the set of elements.
-        `index` to indicate success. It should simply return the same index given, which is the starting index of the set of elements
-.
-        The size of the set of elements that satisfied the predicate, or `nil`
-        Some tranform methods may specify that the 2nd return is optional, such as `transforms.first()`
-    Some transform methods may specify alternative predicate types that can be used, such as tables or strings. These predicate usages are specific to those methods and defined within the method details here.
-==== 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`.
+  与 `string.sub` 作用类似，返回`tbl`从`first`到`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.
+  返回`tbl`中（范围在`first`与`last`索引之间，包含首尾）满足`predicate`的首个元素的索引。第二个返回值为最后一个连续匹配的元素索引。一般而言会返回两个同样的值，即匹配的连续元素为1个。`predicate`可以返回第二个返回值（可选），代表匹配的连续元素序列长度。
-  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`.
+  当`predicate`为表时，`transforms.first()`将会返回`tbl`中首个满足条件的子表的首尾索引值，这种情况下的匹配指匹配`predicate`表中的任一元素。
-  Examples:
+  样例：
 ```lua
@@ Line 75: / Line 65: @@
 ```
-Output
+输出：
 ```
   5
@@ Line 85: / Line 75: @@
 ```
-Output
+输出
 ```
   5
@@ Line 92: / Line 82: @@
 * `transforms.partition(tbl: table, partioner: function, first: number or nil, last: number or nil): table of tables`
-  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.
+  返回一个子表的列表，子表来自`tbl`，由`partioner`生成，范围为从`first`到`last`。`partioner`为判断函数，定义见前文。
-  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`的`index`参数将会跳过范围，即此参数会增加`n`，`n`即为分区大小。
-  The `partitioner` predicate for this method must return the starting AND ending index of satisfied element sets. Again, see the `predicate` info above.
+  此方法的`partitioner`判断函数必须同时返回匹配的元素组的开始与结束索引。请再次参见前文的`predicate`相关信息。
 * `transforms.begins(tbl: table, sub: table, first: number or nil, last: number or nil)`
-  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:
+  若`tbl`从`first`到`last`的子表完全组成了`sub`（自首个元素对齐），则返回`true`。`first`与`last`元素可以正确处理负数。上面的表达也就是说：
   `v[1] == tbl[first + 0]`
@@ Line 111: / Line 101: @@
-  Where `first + #v - 1` is within the bounds of `[first, last]` of `tbl`.
+  此处的`first + #v - 1`在`tbl`的`[first, last]`范围内。.
 * `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.
+  返回`tbl`中从`first`到`last`的每个元素的修改版本。若`adapter`的结果出现`nil`则会被忽略，不会被加入结果。
-  The `adapter` follows the `predicate` signature except for the handling of the return values
+  `adapter`函数遵循判断函数的格式，除了返回值处理方面
-  * **Adapter Returns**
+  * **Adapter函数返回值**
-  The simple case is to return a single value. E.g. `tx.foreach({'a', 'b', 'c'}, string.upper)` would return `{'A', 'B', 'C'}`.
+  简单的情况是返回单个值，例如`tx.foreach({'a', 'b', 'c'}, string.upper)`将会返回`{'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}`.
+  adapter函数可以通过返回`nil`来跳过某个值。例如，`tx.foreach({'1', 'foobar', '2'}, function(n) return tonumber(n) end)`将会返回`{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}`
+  `adapter`函数可以返回第二个值，此值会被用于序号（返回结果键值）。例如`tx.foreach({'1','foobar','3'},function(n,i) return tonumber(n), tostring(i) end)`将会返回`{["1"]=1, ["3"]=3}`