Differences

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

--- api:transforms:zh [2023/10/20 10:21]
hfsr [Methods]
+++ api:transforms:zh [2023/12/01 07:23]
hfsr [Transforms(变换) API]
@@ Line 1: / Line 1: @@
 Transforms(变换)
 =================
-transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是 `text` 与 `sh` 命令解析的核心。
+transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是`text`与`sh`命令解析的核心。
 ===== 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
+    * **元素组**
+    "元素组"一词代指下列之一：
-* **first 与 last**
+    A)传递给判断函数的单个`element`。与`tbl[index]`的值为同一个。
+    或者
-    此API所有的 `first` 与 `last` 参数均与`string`方法（例如`string.sub`）中的 `first` 与 `last` 参数工作方式一致。因此可以接收负值，负值为从后向前数。`first`（当选择时）默认相当于 1，而 `last` 默认相当于 -1。
+    B)`tbl`中自`index`起的元素序列。判断函数可能会从`index`处开始迭代，数量为其需要检查的元素数，直到`#tbl`为止。
+\\
-* **判断函数（predicate，谓词）**
+    * **返回值**
+    返回值的可能情况：
-    译者注：此处的predicate通用的译名是“谓词”，指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名，不利于理解。因此译为“判断函数”。
+    参数1：若为`false` 或 `nil`，代表这组元素不满足判断函数的条件。若为`index`，代表满足条件。函数应当直接返回给定函数的索引号，也就是元素组的起始元素索引号。
+    参数2：满足判断函数的元素组大小，或`nil`。
-    所有接收判断函数的transform方法均使用以下定义：
+    一些tranform方法可能会将第二个参数指定为可选，例如`transforms.first()`。
+\\
-  *  `predicate(element: value, index: number, tbl: table): number, number`
+    一些transform方法可能会指定其他类型的判断函数，例如表或字符串。这些判断函数的用法特定于对应的方法，且在此处详细列出的方法中定义。
-  此判断函数会在 `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方法可能会指定其他可用的判断数据类型，例如表或字符串。这些判断函数的用法特定于对应的方法，且在此处详细列出的方法中定义。
 ==== 方法 ====