Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
Last revision Both sides next revision
api:transforms:zh [2023/10/20 09:36]
hfsr [Transforms(变换) API]
api:transforms:zh [2023/12/01 07:51]
hfsr [方法]
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(tbltablepredicate: function or table, first: number ​or nillastnumber or nil): number, number` ​  
-    译者注:此处predicate通用的译名是“谓词”,指根据条件返回布尔值的函数。但译者认为这是相当糟糕的译名,不利于理解。因此译为“判断函数”。 +  返回`tbl`中(范围在`first``last`索引值之包含首尾)满足`predicate`的个元素的索引值第二个返回值为连续匹配的元素最后一个索引值一般而言会返回两个同样即匹配连续元素为1个。`predicate`可以返回第二个返回值(可选匹配连续元素序长度。   
-     +\\ 
-    ​所有接收判断函数的transform方法均使用以下定义: +  ​`predicate`为表时,`transforms.first()`将会返回`tbl`中首个满足条件的子表的首尾索引值,这种情况下的匹配指匹配`predicate`表中的任一元素。  ​ 
- +\\ 
-  ​ `predicate(elementvalueindex: number, ​tbltable): 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 `indexparameter passed to the `partitionerwill 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 `nilresult of the `adapteris 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}`+