📝 docs(tsl): expand syntax operator and object coverage
This commit is contained in:
@@ -6,19 +6,23 @@
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆，以及怎样读取矩阵的行列大小和索引。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`13` 只讲数组与矩阵样数据，这一篇讲矩阵专用构造、运算与大小接口。
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆、矩阵尺寸与索引、矩阵遍历、子矩阵和 `mfind` 查找。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`12` 讲普通数组与集合关系，这一篇讲矩阵专用构造、遍历、子矩阵和矩阵查找接口。
|
||||
|
||||
## 本篇职责
|
||||
|
||||
回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，以及怎样拿到矩阵的行数、列数、行索引和列索引”。
|
||||
回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，怎样拿到矩阵的行数、列数、行索引和列索引，怎样遍历矩阵、取/改子矩阵，以及怎样用 `mfind` 找到或替换符合条件的单元格”。
|
||||
|
||||
## 智能体矩阵深水判断流程
|
||||
|
||||
1. 先判断要写矩阵初始化、数列构造、矩阵逆/广义逆，还是矩阵尺寸与索引读取。
|
||||
1. 先判断要写矩阵初始化、数列构造、矩阵逆/广义逆、矩阵尺寸与索引读取、矩阵遍历、子矩阵，还是 `mfind` 查找/替换。
|
||||
2. 基础数组和矩阵样比较先回看 `12_matrix_and_collections.md`。
|
||||
3. `mrows` / `mcols` / `msize` 等函数只照文档返回形态写。
|
||||
4. 不要把列索引数组误当成单个数字。
|
||||
5. 没有对应代码块时不要发明矩阵深水写法。
|
||||
4. 需要逐单元执行语句块时用 `matrix::begin ... end`；需要把表达式结果写回每个单元时用 `matrix ::= expression`。
|
||||
5. 需要遍历到嵌套数组最深层时用 `matrix:.begin ... end` 或 `matrix:.= expression`。
|
||||
6. 子矩阵范围使用 `row_start:row_end`、`:`、下标数组和列范围组合；不要把字符串键当作子矩阵范围序号。
|
||||
7. `mfind(...)` 用于把符合条件的单元格转换成下标列表，或同时返回原值/替换原值。
|
||||
8. 不要把列索引数组误当成单个数字。
|
||||
9. 没有对应代码块时不要发明矩阵深水写法。
|
||||
|
||||
## 核心规则
|
||||
|
||||
@@ -35,6 +39,19 @@
|
||||
- `msize(matrix_value, 1)` 返回行索引数组和列索引数组。
|
||||
- `mrows(matrix_value)` / `mcols(matrix_value)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。
|
||||
- `mrows(matrix_value, 1)` / `mcols(matrix_value, 1)` 的返回值可用于索引匹配；不要把它们当成数量。
|
||||
- `matrix::begin ... end` 是矩阵遍历语句块，最多按二维遍历；语句块里可用 `mcell`、`mrow`、`mcol`。
|
||||
- `matrix ::= expression` 是矩阵遍历赋值，把表达式结果逐单元写回原矩阵；它不是语句块。
|
||||
- `matrix:.begin ... end` 是深度遍历语句块；对嵌套数组会遍历到最深节点。
|
||||
- `matrix:.= expression` 是深度遍历赋值；需要对不规则嵌套数组逐叶子节点写回时使用。
|
||||
- 遍历时需要维度信息可用 `mIndexCount`；需要第 `n` 维下标可用 `mIndex(n)`。
|
||||
- 子矩阵提取可以写 `matrix[row_start:row_end, col_start:col_end]`、`matrix[:, col_range]`、`matrix[row_index_array, col_index_array]`。
|
||||
- 子矩阵赋值可以写成单个标量，也可以写成同结构矩阵；赋值矩阵应和目标子矩阵形状匹配。
|
||||
- 子矩阵也可以接 `::=` 做逐单元赋值。
|
||||
- `mfind(matrix)` 返回真值单元格下标；一维数组的无条件 `mfind` 返回一维下标数组。
|
||||
- `mfind(matrix, condition)` 返回符合条件的下标行；二维矩阵下每行形如 `array(row_index, col_index)`。
|
||||
- `mfind(matrix, condition, 1)` 在每个下标行末尾追加原单元值。
|
||||
- `mfind(matrix, condition, ret_value, replacement)` 会把符合条件的单元格替换成 `replacement`，并返回替换前的匹配信息。
|
||||
- `mfindSparse(matrix, condition)` 用于嵌套数组或稀疏结构，返回包含完整深层路径的下标行。
|
||||
|
||||
## 可直接照写示例
|
||||
|
||||
@@ -205,6 +222,311 @@ col_index := mcols(matrix_rows, 1);
|
||||
- `mcols(matrix_rows)` 返回 `2`
|
||||
- `mcols(matrix_rows, 1)` 返回 `array("A", "B")`
|
||||
|
||||
### 矩阵遍历：`::` 与 `::=`
|
||||
|
||||
`::` 执行语句块：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2, 3), (4, 5, 6));
|
||||
sum_value := 0;
|
||||
matrix_value::begin
|
||||
sum_value += mcell;
|
||||
end
|
||||
writeLn(sum_value);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
21
|
||||
```
|
||||
|
||||
`::=` 把表达式结果逐单元写回：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2), (3, 4));
|
||||
matrix_value ::= mrow * 10 + mcol;
|
||||
writeLn(matrix_value[0][0]);
|
||||
writeLn(matrix_value[0][1]);
|
||||
writeLn(matrix_value[1][0]);
|
||||
writeLn(matrix_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
0
|
||||
1
|
||||
10
|
||||
11
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `mcell` 是当前单元格值。
|
||||
- `mrow` 是当前行下标。
|
||||
- `mcol` 是当前列下标。
|
||||
- `::=` 右侧写表达式，不写 `begin ... end` 语句块。
|
||||
|
||||
### 深度遍历：`:.` 与 `:.=`
|
||||
|
||||
`:.` 会遍历到嵌套数组的最深节点：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
nested_value := array(10, 12, ("A": array(30), "B": 22), ("A": array(31, 32), "B": 23));
|
||||
deep_count := 0;
|
||||
nested_value:.begin
|
||||
deep_count += 1;
|
||||
end
|
||||
writeLn(deep_count);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
7
|
||||
```
|
||||
|
||||
`:.=` 会把表达式结果写回最深节点：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
values := array(-1, 2, -3);
|
||||
values:.= abs(mcell);
|
||||
writeLn(values[0]);
|
||||
writeLn(values[1]);
|
||||
writeLn(values[2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
1
|
||||
2
|
||||
3
|
||||
```
|
||||
|
||||
### 子矩阵
|
||||
|
||||
按行列范围提取：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2, 3), (4, 5, 6), (7, 8, 9));
|
||||
sub_value := matrix_value[1:2, 0:1];
|
||||
writeLn(mrows(sub_value));
|
||||
writeLn(mcols(sub_value));
|
||||
writeLn(sub_value[0][0]);
|
||||
writeLn(sub_value[0][1]);
|
||||
writeLn(sub_value[1][0]);
|
||||
writeLn(sub_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
2
|
||||
4
|
||||
5
|
||||
7
|
||||
8
|
||||
```
|
||||
|
||||
按下标数组提取：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2, 3), (4, 5, 6), (7, 8, 9));
|
||||
sub_value := matrix_value[array(0, 2), array(1, 2)];
|
||||
writeLn(sub_value[0][0]);
|
||||
writeLn(sub_value[0][1]);
|
||||
writeLn(sub_value[1][0]);
|
||||
writeLn(sub_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
3
|
||||
8
|
||||
9
|
||||
```
|
||||
|
||||
子矩阵赋值：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2, 3), (4, 5, 6), (7, 8, 9));
|
||||
matrix_value[0:1, 1:2] := array((10, 11), (12, 13));
|
||||
writeLn(matrix_value[0][1]);
|
||||
writeLn(matrix_value[0][2]);
|
||||
writeLn(matrix_value[1][1]);
|
||||
writeLn(matrix_value[1][2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
10
|
||||
11
|
||||
12
|
||||
13
|
||||
```
|
||||
|
||||
子矩阵逐单元赋值：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 2), (3, 4));
|
||||
matrix_value[0:1, 0:1] ::= mrow * 10 + mcol;
|
||||
writeLn(matrix_value[0][0]);
|
||||
writeLn(matrix_value[0][1]);
|
||||
writeLn(matrix_value[1][0]);
|
||||
writeLn(matrix_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
0
|
||||
1
|
||||
10
|
||||
11
|
||||
```
|
||||
|
||||
### `mfind` 与 `mfindSparse`
|
||||
|
||||
一维数组无条件查找会返回一维下标数组：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
values := array(1, 0, 2, 0, 3);
|
||||
indexes := mfind(values);
|
||||
writeLn(length(indexes));
|
||||
writeLn(indexes[0]);
|
||||
writeLn(indexes[1]);
|
||||
writeLn(indexes[2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
3
|
||||
0
|
||||
2
|
||||
4
|
||||
```
|
||||
|
||||
二维矩阵按条件查找：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 0), (2, 3));
|
||||
indexes := mfind(matrix_value, mcell >= 2);
|
||||
writeLn(length(indexes));
|
||||
writeLn(indexes[0][0]);
|
||||
writeLn(indexes[0][1]);
|
||||
writeLn(indexes[1][0]);
|
||||
writeLn(indexes[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
1
|
||||
0
|
||||
1
|
||||
1
|
||||
```
|
||||
|
||||
第三个参数写成 `1` 时，每行末尾追加原单元值：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 0), (2, 3));
|
||||
matches := mfind(matrix_value, mcell >= 2, 1);
|
||||
writeLn(matches[0][0]);
|
||||
writeLn(matches[0][1]);
|
||||
writeLn(matches[0][2]);
|
||||
writeLn(matches[1][0]);
|
||||
writeLn(matches[1][1]);
|
||||
writeLn(matches[1][2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
1
|
||||
0
|
||||
2
|
||||
1
|
||||
1
|
||||
3
|
||||
```
|
||||
|
||||
第四个参数用于替换符合条件的单元格：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
matrix_value := array((1, 0), (2, 3));
|
||||
matches := mfind(matrix_value, mcell >= 2, 1, 100);
|
||||
writeLn(matches[0][2]);
|
||||
writeLn(matches[1][2]);
|
||||
writeLn(matrix_value[1][0]);
|
||||
writeLn(matrix_value[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
3
|
||||
100
|
||||
100
|
||||
```
|
||||
|
||||
`mfindSparse` 返回深层路径：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
nested_value := array(10, ("A": 0, "B": array(2)), 0);
|
||||
indexes := mfindSparse(nested_value, mcell = 2);
|
||||
writeLn(length(indexes));
|
||||
writeLn(length(indexes[0]));
|
||||
writeLn(indexes[0][0]);
|
||||
writeLn(indexes[0][1]);
|
||||
writeLn(indexes[0][2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
1
|
||||
3
|
||||
1
|
||||
B
|
||||
0
|
||||
```
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
需要矩阵构造时，优先从这个最短模板开始：
|
||||
@@ -222,6 +544,9 @@ matrix_value := zeros(2, 3);
|
||||
- 以为 `mrows(matrix_value, 1)` 和 `mcols(matrix_value, 1)` 返回的还是数量。
|
||||
- 写带步长的 `->` 时，漏掉外层 `array(...)`。
|
||||
- 还在普通数组页里硬塞矩阵专用大小接口。
|
||||
- 把 `::=` 写成带 `begin ... end` 的语句块。
|
||||
- 用 `::` 期待遍历到任意深度；深度遍历使用 `:.`。
|
||||
- 子矩阵赋值时用形状不匹配的矩阵硬塞。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
|
||||
|
||||
Reference in New Issue
Block a user