🎨 style(syntax): normalize naming conventions
Align all TSL syntax documentation examples with docs/tsl/naming.md: - Classes/types: PascalCase, drop Hungarian prefix (THuman→Human) - Parameters/locals: snake_case with meaningful names (isLeft→is_left, maxb→max_b) - Private members: snake_case_ with trailing underscore (real_part_, imaginary_part_) - Public members: PascalCase (value→Value) - Top-level functions: PascalCase (test→Test) - Module constants: kPascalCase (kernel_dll→kKernelDll) Affected: 01-24 syntax docs (23 files) Verified: 150+ code blocks locally tested, output unchanged Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Claude Fable 5
@@ -6,11 +6,11 @@
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[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)
|
||||
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆、矩阵尺寸与索引、矩阵遍历、子矩阵和 `mfind` 查找。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`12` 讲普通数组与集合关系，这一篇讲矩阵专用构造、遍历、子矩阵和矩阵查找接口。
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆、矩阵乘除乘方、矩阵转置、矩阵拼接、矩阵尺寸与索引、矩阵遍历、子矩阵和 `mfind` 查找。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`12` 讲普通数组与集合关系，这一篇讲矩阵专用构造、运算、遍历、子矩阵和矩阵查找接口。
|
||||
|
||||
## 本篇职责
|
||||
|
||||
回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，怎样拿到矩阵的行数、列数、行索引和列索引，怎样遍历矩阵、取/改子矩阵，以及怎样用 `mfind` 找到或替换符合条件的单元格”。
|
||||
回答”怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，怎样进行矩阵乘除乘方，怎样转置矩阵，怎样拼接矩阵，怎样拿到矩阵的行数、列数、行索引和列索引，怎样遍历矩阵、取/改子矩阵，以及怎样用 `mfind` 找到或替换符合条件的单元格”。
|
||||
|
||||
## 智能体矩阵深水判断流程
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
|
||||
## 核心规则
|
||||
|
||||
- 矩阵初始化函数的参数规格见 [../reference/catalog/math.md](../reference/catalog/math.md)；本页只保留矩阵行为示例和返回形态边界。
|
||||
- 矩阵初始化函数的参数规格见 [../codegen/builtin/math.md](../codegen/builtin/math.md)；本页只保留矩阵行为示例和返回形态边界。
|
||||
- `zeros(...)`、`ones(...)`、`rand(...)`、`nils(...)`、`eye(...)` 都可以直接用于矩阵初始化。
|
||||
- `zeros(3)`、`ones(3)`、`nils(2)` 这类单参数写法可以直接生成一维结果。
|
||||
- `zeros(2, 3)`、`rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。
|
||||
@@ -34,7 +34,7 @@
|
||||
- `eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。
|
||||
- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。
|
||||
- 在矩阵语境里，`!A` 是一元倒数运算符作用于矩阵的形态，用于矩阵逆/广义逆；非方阵输入可以返回行列数互换后的广义逆结果。
|
||||
- `msize(...)`、`mrows(...)`、`mcols(...)` 的参数规格见 [../reference/catalog/system.md](../reference/catalog/system.md)。
|
||||
- `msize(...)`、`mrows(...)`、`mcols(...)` 的参数规格见 [../codegen/special/pending/system/01_data_type.md](../codegen/special/pending/system/01_data_type.md)。
|
||||
- `msize(matrix_value)` 返回 `array(行数, 列数)`。
|
||||
- `msize(matrix_value, 1)` 返回行索引数组和列索引数组。
|
||||
- `mrows(matrix_value)` / `mcols(matrix_value)` 默认返回数量；第二个参数写成 `1` 时返回索引数组。
|
||||
@@ -527,6 +527,380 @@ B
|
||||
0
|
||||
```
|
||||
|
||||
### 矩阵乘法、除法、乘方：`:*`、`:/`、`:^`
|
||||
|
||||
`:*` 是矩阵乘法（区别于逐元素乘 `*`）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2), (3, 4));
|
||||
b := array((5, 6), (7, 8));
|
||||
element_wise := a * b;
|
||||
matrix_multiply := a :* b;
|
||||
writeLn("逐元素乘 (0,0):", element_wise[0][0]);
|
||||
writeLn("矩阵乘 (0,0):", matrix_multiply[0][0]);
|
||||
writeLn("矩阵乘 (0,1):", matrix_multiply[0][1]);
|
||||
writeLn("矩阵乘 (1,0):", matrix_multiply[1][0]);
|
||||
writeLn("矩阵乘 (1,1):", matrix_multiply[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
逐元素乘 (0,0): 5
|
||||
矩阵乘 (0,0): 19
|
||||
矩阵乘 (0,1): 22
|
||||
矩阵乘 (1,0): 43
|
||||
矩阵乘 (1,1): 50
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `*` 是逐元素乘（element-wise），`a * b` 的 `(0,0)` 是 `1 * 5 = 5`
|
||||
- `:*` 是真正的矩阵乘法，`a :* b` 的 `(0,0)` 是 `1*5 + 2*7 = 19`
|
||||
- 矩阵乘法要求左矩阵列数等于右矩阵行数
|
||||
|
||||
`:/` 是矩阵除法（等价于 `A :* !B`）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2), (3, 4));
|
||||
b := array((2, 0), (0, 2));
|
||||
result := a :/ b;
|
||||
writeLn(result[0][0]);
|
||||
writeLn(result[0][1]);
|
||||
writeLn(result[1][0]);
|
||||
writeLn(result[1][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
0.5
|
||||
1
|
||||
1.5
|
||||
2
|
||||
```
|
||||
|
||||
`:\` 是矩阵左除（等价于 `!A :* B`，常用于解线性方程组）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((2, 0), (0, 4));
|
||||
b := array((4), (8));
|
||||
result := a :\ b;
|
||||
writeLn(result[0][0]);
|
||||
writeLn(result[1][0]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
2
|
||||
2
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `:\` 左除用于解线性方程组 `A * X = B`，等价于 `X = A^(-1) * B`
|
||||
- **右侧 `b` 必须是列向量**（用 `array((4), (8))` 而非 `array(4, 8)`）
|
||||
- `a :\ b` 返回 `array((2.0), (2.0))`，即 `X` 的列向量
|
||||
- 当 A 行数 > 列数时返回最小二乘解，行数 < 列数时返回一个可行解
|
||||
|
||||
`:^` 是矩阵乘方（`A :^ 2` 等价于 `A :* A`）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 1), (0, 1));
|
||||
pow2 := a :^ 2;
|
||||
manual := a :* a;
|
||||
writeLn("pow (0,0):", pow2[0][0]);
|
||||
writeLn("pow (0,1):", pow2[0][1]);
|
||||
writeLn("pow (1,1):", pow2[1][1]);
|
||||
writeLn("manual (0,1):", manual[0][1]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
pow (0,0): 1
|
||||
pow (0,1): 2
|
||||
pow (1,1): 1
|
||||
manual (0,1): 2
|
||||
```
|
||||
|
||||
复合赋值算符：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2), (3, 4));
|
||||
b := array((1, 0), (0, 1));
|
||||
a :*= b;
|
||||
writeLn(a[0][0]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
1
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `:*=`、`:/=`、`:\=`、`:^=` 分别是矩阵乘、除、左除、乘方的复合赋值形式
|
||||
- `a :*= b` 等价于 `a := a :* b`
|
||||
|
||||
### 基础函数的矩阵广播与异常处理参数
|
||||
|
||||
多参数基础函数支持逐参数广播：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
data := array(1.55, 2.99, 3.85);
|
||||
precision := array(-1, 0, 0);
|
||||
result := RoundTo(data, precision);
|
||||
writeLn(result[0]);
|
||||
writeLn(result[1]);
|
||||
writeLn(result[2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
1.6
|
||||
3
|
||||
4
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `RoundTo(data, precision)` 对两个数组逐元素配对：`RoundTo(1.55, -1)` → `1.6`、`RoundTo(2.99, 0)` → `3.0`
|
||||
- 规则：为每个参数寻找一个或一组匹配者，逐参数广播
|
||||
|
||||
基础函数尾部可追加异常处理参数 `ErrDefine` 和 `ErrReplace`：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
data := array(4, -1, 9);
|
||||
result := sqrt(data, 1, -999);
|
||||
writeLn(tostn(result));
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
array(2.0,NAN,3.0)
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `sqrt(data, 1, -999)` 中，第二参数 `ErrDefine=1` 表示允许 NIL 值不允许错误值
|
||||
- `ErrReplace=-999` 是错误位置的替换值（本例中 `-1` 的平方根为错误，但 `ErrDefine=1` 保留为 NAN）
|
||||
- `ErrDefine` 取值：`0`=不允许错误和 NIL、`1`=允许 NIL 不允许错误、`2`=错误值保留为原值
|
||||
- `ErrReplace` 在 `ErrDefine=0` 或 `1` 时生效，用于替换错误/NIL 位置
|
||||
|
||||
另一个例子：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
data := array(1, nil, "AAA", -100);
|
||||
result := abs(data, 0, -999);
|
||||
writeLn(tostn(result));
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
array(1,-999,-999,100)
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `abs(data, 0, -999)` 中，`ErrDefine=0` 不允许错误和 NIL
|
||||
- `nil` 和 `"AAA"` 都被替换成 `-999`
|
||||
- 对于多参数基础函数，`ErrDefine` 和 `ErrReplace` 总是可以作为可选参数添加在最后
|
||||
|
||||
### 矩阵转置：反引号 `` ` ``
|
||||
|
||||
单次转置交换行列：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2, 3), (4, 5, 6));
|
||||
transposed := `a;
|
||||
writeLn("原矩阵行数:", mrows(a));
|
||||
writeLn("原矩阵列数:", mcols(a));
|
||||
writeLn("转置后行数:", mrows(transposed));
|
||||
writeLn("转置后列数:", mcols(transposed));
|
||||
writeLn("转置 (0,0):", transposed[0][0]);
|
||||
writeLn("转置 (1,0):", transposed[1][0]);
|
||||
writeLn("转置 (2,0):", transposed[2][0]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
原矩阵行数: 2
|
||||
原矩阵列数: 3
|
||||
转置后行数: 3
|
||||
转置后列数: 2
|
||||
转置 (0,0): 1
|
||||
转置 (1,0): 2
|
||||
转置 (2,0): 3
|
||||
```
|
||||
|
||||
一维数组转置成列向量：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
b := array(1, 2, 3);
|
||||
col_vector := `b;
|
||||
writeLn("一维长度:", length(b));
|
||||
writeLn("列向量行数:", mrows(col_vector));
|
||||
writeLn("列向量列数:", mcols(col_vector));
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
一维长度: 3
|
||||
列向量行数: 3
|
||||
列向量列数: 1
|
||||
```
|
||||
|
||||
双转置把一维数组变成行向量（常用于 `union` 追加行）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
b := array(1, 2, 3);
|
||||
row_vector := ``b;
|
||||
writeLn("行向量行数:", mrows(row_vector));
|
||||
writeLn("行向量列数:", mcols(row_vector));
|
||||
writeLn("行向量 (0,0):", row_vector[0][0]);
|
||||
writeLn("行向量 (0,1):", row_vector[0][1]);
|
||||
writeLn("行向量 (0,2):", row_vector[0][2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
行向量行数: 1
|
||||
行向量列数: 3
|
||||
行向量 (0,0): 1
|
||||
行向量 (0,1): 2
|
||||
行向量 (0,2): 3
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `` `a `` 是后缀算符，写在矩阵变量或表达式之后
|
||||
- 一维数组 `b` 转置一次成列向量（3行1列），转置两次成行向量（1行3列）
|
||||
- 双转置技巧常配合 `union` 逐行追加数据
|
||||
|
||||
### 矩阵拼接：`union`、`&=`、`|`、`:|`
|
||||
|
||||
`union` 按行拼接（一维或二维）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array(1, 2, 3);
|
||||
b := array(4, 5, 6);
|
||||
result := a union b;
|
||||
writeLn(length(result));
|
||||
writeLn(result[0]);
|
||||
writeLn(result[3]);
|
||||
writeLn(result[5]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
6
|
||||
1
|
||||
4
|
||||
6
|
||||
```
|
||||
|
||||
`&=` 是 `union` 的复合赋值形式（注意不是 `union=`）：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array(1, 2, 3);
|
||||
b := array(4, 5, 6);
|
||||
a &= b;
|
||||
writeLn(length(a));
|
||||
writeLn(a[5]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
6
|
||||
6
|
||||
```
|
||||
|
||||
`|` 按列拼接：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2), (3, 4));
|
||||
b := array((5, 6), (7, 8));
|
||||
result := a | b;
|
||||
writeLn("列数:", mcols(result));
|
||||
writeLn("(0,2):", result[0][2]);
|
||||
writeLn("(1,3):", result[1][3]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
列数: 4
|
||||
(0,2): 5
|
||||
(1,3): 8
|
||||
```
|
||||
|
||||
`:|` 对非完全矩阵补 `nil`，`|` 不补：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
a := array((1, 2, 3), (2, 3));
|
||||
colon_result := a :| a;
|
||||
bar_result := a | a;
|
||||
writeLn("colon 结果列数:", mcols(colon_result));
|
||||
writeLn("colon (1,2):", colon_result[1][2]);
|
||||
writeLn("bar 结果 (1,2):", bar_result[1][2]);
|
||||
```
|
||||
|
||||
代码块身份：输出片段
|
||||
|
||||
```text
|
||||
colon 结果列数: 6
|
||||
colon (1,2): nil
|
||||
bar 结果 (1,2): 1
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `union` / `&=` 用于行方向拼接
|
||||
- `|` / `:|` 用于列方向拼接
|
||||
- 非完全矩阵（行长度不一致）用 `:|` 会在缺位补 `nil`，而 `|` 不补
|
||||
- 对应的复合赋值形式：`&=`（行并）、`|=`（列并）、`:|=`（列并补 nil）
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
需要矩阵构造时，优先从这个最短模板开始：
|
||||
@@ -541,12 +915,18 @@ matrix_value := zeros(2, 3);
|
||||
|
||||
- 把 `eye(3)` 当成一维数组。
|
||||
- 把 `!A` 当成逻辑非表达式。
|
||||
- 把 `*` 当成矩阵乘法；矩阵乘法使用 `:*`。
|
||||
- 把 `:*`、`:/`、`:\`、`:^` 当成逐元素运算；逐元素运算使用 `*`、`/`、`^`。
|
||||
- 在 `:\` 左除时，右侧用一维数组而非列向量；右侧必须用 `array((v1), (v2), ...)` 形式。
|
||||
- 以为 `mrows(matrix_value, 1)` 和 `mcols(matrix_value, 1)` 返回的还是数量。
|
||||
- 写带步长的 `->` 时，漏掉外层 `array(...)`。
|
||||
- 还在普通数组页里硬塞矩阵专用大小接口。
|
||||
- 把 `::=` 写成带 `begin ... end` 的语句块。
|
||||
- 用 `::` 期待遍历到任意深度；深度遍历使用 `:.`。
|
||||
- 子矩阵赋值时用形状不匹配的矩阵硬塞。
|
||||
- 把 `union` 的复合赋值写成 `union=`；正确写法是 `&=`。
|
||||
- 一维数组直接 `union` 期待得到二维结果；需要先双转置 `` ``b `` 变成行向量。
|
||||
- 在基础函数异常参数时用分号分隔；正确写法用逗号：`sqrt(data, 1, -999)`。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
|
||||
|
||||
Reference in New Issue
Block a user