Differences

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

Link to this comparison view

Next revision 		Previous revision
api:transforms:zh [2022/08/11 10:50]
fight_xing created 		api:transforms:zh [2023/12/01 07:52] (current)
hfsr [Transforms(变换) API]
Line 1: Line 1:
-Transforms+Transforms(变换)
 ================= =================
 +transforms(变换)库提供了一套用于带索引表的实用工具。此运行库提供了高度可复用的特殊迭代器，这些迭代器是`text`与`sh`命令解析的核心。
 +===== Transforms(变换) API =====
  
-**本篇文章的部分/全部内容还没有进行翻译。**+* **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`]范围内的值。 ​  
 +\\ 
 +  换言之，判断函数处理“一组元素”，并返回代表所满足条件的值。
  
-The transforms library is set of utilities for working with indexed tables. It provides highly reusable special iterators that are at the core of `text` and `sh` command parsing. +    * **元素组** ​  
-===== Transforms API =====+    "​元素组"​一词代指下列之一： ​  
 +    A)传递给判断函数的单个`element`。与`tbl[index]`的值为同一个。 ​  
 +    或者 ​  
 +    B)`tbl`中自`index`起的元素序列。判断函数可能会从`index`处开始迭代，数量为其需要检查的元素数，直到`#​tbl`为止。 ​  
 +\\ 
 +    * **返回值** ​  
 +    返回值的可能情况： ​  
 +    参数1：若为`false` 或 `nil`，代表这组元素不满足判断函数的条件。若为`index`，代表满足条件。函数应当直接返回给定函数的索引号，也就是元素组的起始元素索引号。 ​  
 +    参数2：满足判断函数的元素组大小，或`nil`。 ​  
 +    一些tranform方法可能会将第二个参数指定为可选，例如`transforms.first()`。 ​  
 +\\ 
 +一些transform方法可能会指定其他类型的判断类型，例如表或字符串。这些判断函数的用法特定于对应的方法，且在此处详细列出的方法中定义。
  
-* **Transforms work on _sequences_**+==== 方法 ====
  
-    All transforms methods expect to iterate over sequences, see https://​www.lua.org/​manual/​5.2/​manual.html#​3.4.6 +* `transforms.sub(tbl:​ table, first: number, last: number or nil): table` ​  
- +  ​与`string.sub`作用类似，返回`tbl`从`first`到`last`的子表。  ​ 
-* **first and last** +\\ 
- +* `transforms.first(tbl:​ table, predicate: function or table, first: number or nil, last: number or nil): number, number` ​  
-    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. +  ​返回`tbl`中（范围在`first`与`last`索引值之间，包含首尾）满足`predicate`的首个元素的索引值。第二个返回值为连续匹配的元素最后一个的索引值。一般而言会返回两个同样的值，即匹配的连续元素为1个。`predicate`可以返回第二个返回值（可选），代表匹配的连续元素序列长度。  ​ 
- +\\ 
-* **The Predicate** +  ​当`predicate`为表时，`transforms.first()`将会返回`tbl`中首个满足条件的子表的首尾索引值，这种情况下的匹配指匹配`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 +
-    1 +
-        `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 +
-    2. +
-        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`. +
- +
-* `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 78: Line 63:
 ``` ```
  
-Output+输出：
 ``` ```
 4  5 4  5
Line 88: 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}`+