# TSL 矩阵深水专题

这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆、矩阵乘除乘方、矩阵转置、矩阵拼接、矩阵尺寸与索引、矩阵遍历、子矩阵和 `mfind` 查找。它和 [11_matrix_and_collections.md](11_matrix_and_collections.md) 的分工是：`11` 讲普通数组与集合关系，这一篇讲矩阵专用构造、运算、遍历、子矩阵和矩阵查找接口。

## 本篇职责

<!-- section-id: syntax-21-001 -->

回答“怎样直接构造全零矩阵、全一矩阵、随机矩阵、单位矩阵、空矩阵和数列数组，怎样写矩阵逆/广义逆，怎样进行矩阵乘除乘方，怎样转置矩阵，怎样拼接矩阵，怎样拿到矩阵的行数、列数、行索引和列索引，怎样遍历矩阵、取/改子矩阵，以及怎样用 `mfind` 找到或替换符合条件的单元格”。

## 核心规则

<!-- section-id: syntax-21-002 -->

本页示例只说明矩阵语法中的调用位置、运算结构和源码外形。矩阵 API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对，不能由本页示例反推。

- 矩阵初始化和基础函数的具体参数规格使用 `tsl-api-reference` skill 按名查询；本页只保留矩阵行为示例、返回形态边界和跨函数通用的广播 / `ErrDefine` / `ErrReplace` 机制。
- `zeros(...)`、`ones(...)`、`rand(...)`、`nils(...)`、`eye(...)` 都可以直接用于矩阵初始化；全 `nil` 单元的“空矩阵”用 `nils(...)` 构造。
- `zeros(3)`、`ones(3)`、`nils(2)` 这类单参数写法可以直接生成一维结果。
- `zeros(2, 3)`、`rand(2, 3)` 这类双参数写法可以直接生成二维矩阵。
- `zeros(2, array("A", "B"))` 这种写法可以直接生成带列名的二维结果。
- `eye(3)` 生成的是 `3 x 3` 单位矩阵，不是一维数组。
- `->` 用来生成数列；默认步长是 `1`，也可以显式传入步长和索引数组。
- 在矩阵语境里，`!A` 是一元倒数运算符作用于矩阵的形态，用于矩阵逆/广义逆；非方阵输入可以返回行列数互换后的广义逆结果。
- `msize(matrix_value)` 返回 `array(行数, 列数)`。
- `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]`。
- 子矩阵赋值可以写成单个标量，也可以写成同结构矩阵；赋值矩阵应和目标子矩阵形状匹配。
- 子矩阵赋值语句本身**没有返回值**：`(m[:, "a"] := v)` 求值为 `0`，而普通赋值 `(a := v)` 求值为被赋的值。不要把子矩阵赋值写在需要取值的位置。
- `t[:, :] := source` 按**位置**逐单元复制，不按列名对齐。`source` 里若有某行的列存储顺序与其它行不同，复制结果会静默错位；先用 `source[:, array("列1", "列2")]` 统一列序再赋值。
- 子矩阵也可以接 `::=` 做逐单元赋值。
- `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)` 用于嵌套数组或稀疏结构，返回包含完整深层路径的下标行。

## 可直接照写示例

<!-- section-id: syntax-21-003 -->

### 矩阵初始化

<!-- section-id: syntax-21-004 -->

<!-- tags: 建矩阵, 全零矩阵, 全一矩阵, 单位阵, 初始化二维 -->

代码块身份：可直接照写示例

```tsl
zeros_1d := zeros(3);
zeros_2d := zeros(2, 3);
ones_1d := ones(3);
nils_1d := nils(2);
eye_2d := eye(3);
rand_2d := rand(2, 3);
named_zeros := zeros(2, array("A", "B"));
writeLn(length(zeros_1d));
writeLn(mrows(zeros_2d));
writeLn(mcols(zeros_2d));
```

结果说明：

- `zeros(3)` 的长度是 `3`，前三个元素依次是 `0`、`0`、`0`
- `zeros(2, 3)` 的行数是 `2`、列数是 `3`，第一行前三个元素是 `0`、`0`、`0`
- `ones(3)` 的前三个元素依次是 `1`、`1`、`1`
- `nils(2)` 可直接生成长度为 `2` 的结果
- `eye(3)` 的行数是 `3`、列数是 `3`，并且 `(0,0)`、`(1,1)`、`(2,2)` 为 `1`，`(0,1)`、`(1,0)` 为 `0`
- `rand(2, 3)` 的行数是 `2`、列数是 `3`
- `zeros(2, array("A", "B"))` 的行数是 `2`、列数是 `2`，并且 `named_zeros[0]["A"]`、`named_zeros[0]["B"]`、`named_zeros[1]["A"]`、`named_zeros[1]["B"]` 都是 `0`

代码块身份：输出片段

```text
3
2
3
```

### `->` 数列数组初始化

<!-- section-id: syntax-21-005 -->

<!-- tags: 生成序列, 等差数列, 从几到几, 连续数字 -->

默认步长为 `1`：

代码块身份：可直接照写示例

```tsl
seq_default := 1 -> 5;
```

结果说明：

- `seq_default` 是 `array(1, 2, 3, 4, 5)`

显式指定步长：

代码块身份：可直接照写示例

```tsl
seq_step := array(2.5, 0.5) -> 5;
```

结果说明：

- `seq_step` 的长度是 `6`
- 六个元素依次是 `2.5`、`3`、`3.5`、`4`、`4.5`、`5`

显式指定索引数组：

代码块身份：可直接照写示例

```tsl
seq_indexed := array(0, 1, array("A", "B", "C", "D", "E", "F")) -> 5;
```

结果说明：

- `seq_indexed` 的长度是 `6`
- `seq_indexed["A"]` 到 `seq_indexed["F"]` 依次是 `0`、`1`、`2`、`3`、`4`、`5`

### 矩阵一元倒数 / 逆 / 广义逆：`!A`

<!-- section-id: syntax-21-006 -->

<!-- tags: 求逆, 逆矩阵, 广义逆, 解方程 -->

方阵输入返回普通矩阵逆：

代码块身份：可直接照写示例

```tsl
matrix_value := array((1, 2), (3, 4));
inverse_value := !matrix_value;
writeLn(mrows(inverse_value));
writeLn(mcols(inverse_value));
writeLn(inverse_value[0][0]);
writeLn(inverse_value[0][1]);
writeLn(inverse_value[1][0]);
writeLn(inverse_value[1][1]);
```

代码块身份：输出片段

```text
2
2
-2
1
1.5
-0.5
```

非方阵输入返回广义逆：

代码块身份：可直接照写示例

```tsl
matrix_value := array((1, 2, 3), (4, 5, 6));
inverse_value := !matrix_value;
writeLn(mrows(inverse_value));
writeLn(mcols(inverse_value));
writeLn(inverse_value[0][0]);
writeLn(inverse_value[0][1]);
writeLn(inverse_value[1][0]);
writeLn(inverse_value[1][1]);
writeLn(inverse_value[2][0]);
writeLn(inverse_value[2][1]);
```

代码块身份：输出片段

```text
3
2
-0.944444444444444
0.444444444444444
-0.111111111111111
0.111111111111111
0.722222222222222
-0.222222222222222
```

说明：

- `array((1, 2, 3), (4, 5, 6))` 是 `2 x 3` 矩阵样数组。
- `!matrix_value` 返回的是 `3 x 2` 广义逆结果。
- 生成矩阵逆/广义逆时写 `!matrix_value`；不要把它改写成 `1 / matrix_value`。
- `!` 不表示逻辑非；逻辑非以 [06_expressions_and_operators.md](06_expressions_and_operators.md) 的 `not` 规则为准。

### `msize`、`mrows`、`mcols`

<!-- section-id: syntax-21-007 -->

<!-- tags: 矩阵几行几列, 尺寸, 维度大小, 行数列数 -->

代码块身份：可直接照写示例

```tsl
matrix_rows := array(
    ("A": 1, "B": 2),
    ("A": 11, "B": 22),
    ("A": 21, "B": 32)
);
size_info := msize(matrix_rows);
size_index := msize(matrix_rows, 1);
row_count := mrows(matrix_rows);
row_index := mrows(matrix_rows, 1);
col_count := mcols(matrix_rows);
col_index := mcols(matrix_rows, 1);
```

结果说明：

- `msize(matrix_rows)` 返回 `array(3, 2)`
- `msize(matrix_rows, 1)` 的第一项是 `array(0, 1, 2)`，第二项是 `array("A", "B")`
- `mrows(matrix_rows)` 返回 `3`
- `mrows(matrix_rows, 1)` 返回 `array(0, 1, 2)`
- `mcols(matrix_rows)` 返回 `2`
- `mcols(matrix_rows, 1)` 返回 `array("A", "B")`

### 矩阵遍历：`::` 与 `::=`

<!-- section-id: syntax-21-008 -->

<!-- tags: 遍历矩阵, 逐格处理, 二维循环, 批量赋值 -->

`::` 执行语句块：

代码块身份：可直接照写示例

```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` 语句块。

### 深度遍历：`:.` 与 `:.=`

<!-- section-id: syntax-21-009 -->

<!-- tags: 遍历嵌套数组, 递归遍历, 最深层元素 -->

`:.` 会遍历到嵌套数组的最深节点：

代码块身份：可直接照写示例

```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
```

### 子矩阵

<!-- section-id: syntax-21-010 -->

<!-- tags: 取一块, 切片, 按行列范围取, 局部矩阵 -->

按行列范围提取：

代码块身份：可直接照写示例

```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
```

### 子矩阵赋值的返回值与对齐方式

<!-- section-id: syntax-21-019 -->

<!-- tags: 赋值返回0, 赋值没返回值, 重构数组错位, 按位置复制, 列顺序不一致 -->

子矩阵赋值不产生返回值，普通赋值才产生：

代码块身份：可直接照写示例

```tsl
source := array(1, 2, 3);
plain := (target := source);
writeLn("plain:", plain[0]);

matrix_value := zeros(3, "a");
sub := (matrix_value[:, "a"] := source);
writeLn("sub:", sub);
writeLn("written:", matrix_value[0]["a"]);
```

结果说明：

- `plain` 拿到被赋的数组，所以 `plain[0]` 输出 `1`
- `sub` 输出 `0`：子矩阵赋值语句本身求值为 `0`，不是被赋的值
- `written` 输出 `1`：赋值本身生效了，只是取不到返回值
- 所以 `return m[:, "a"] := v;` 这种写法会返回 `0`，要分成两句写

代码块身份：输出片段

```text
plain:1
sub:0
written:1
```

`t[:, :] := source` 按位置复制，不按列名对齐：

代码块身份：可直接照写示例

```tsl
source := array("k1": ("p": 651, "v": 637),
                "k2": ("p": 599, "v": 170),
                "k3": ("v": 200, "p": 607));
target := zeros(mRows(source), mCols(source, 1));
target[:, :] := source;
writeLn("row3 p:", target[2]["p"]);
writeLn("row3 v:", target[2]["v"]);

ordered := source[:, array("p", "v")];
fixed := zeros(mRows(ordered), mCols(ordered, 1));
fixed[:, :] := ordered;
writeLn("fixed p:", fixed[2]["p"]);
writeLn("fixed v:", fixed[2]["v"]);
```

结果说明：

- 第三行源数据的列存储顺序是 `v`、`p`，与前两行相反
- `row3 p` 输出 `200`、`row3 v` 输出 `607`：两个值互换了，因为复制按位置而不按列名
- 前两行看不出问题，所以这种错位不会报错，只会静默出现在个别行
- `ordered := source[:, array("p", "v")]` 先统一列序后，`fixed p` 输出 `607`、`fixed v` 输出 `200`，恢复正确
- 源数据由多个过程分别写入时，各行列序可能不一致，用 `[:, :]` 重构前先统一列序

代码块身份：输出片段

```text
row3 p:200
row3 v:607
fixed p:607
fixed v:200
```

### `mfind` 与 `mfindSparse`

<!-- section-id: syntax-21-011 -->

<!-- tags: 在矩阵里查找, 找位置, 满足条件的下标, 稀疏查找 -->

一维数组无条件查找会返回一维下标数组：

代码块身份：可直接照写示例

```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
```

### 矩阵乘法、除法、左除、乘方：`:*`、`:/`、`:\`、`:^`

<!-- section-id: syntax-21-012 -->

<!-- tags: 矩阵相乘, 矩阵乘方, 左除, 区别于逐元素乘 -->

`:*` 是矩阵乘法（区别于逐元素乘 `*`）：

代码块身份：可直接照写示例

```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
```

说明：

- `:\` 左除用于解线性方程组 AX = B（数学记法），等价于先求逆再矩阵乘：`!a :* 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`

### 基础函数的矩阵广播与无效输入替换参数

<!-- section-id: syntax-21-013 -->

<!-- tags: 对整个矩阵取整, 函数作用于每个元素, 广播, 出错时给默认值, 无效输入替换, errdefine, errreplace -->

多参数基础函数支持逐参数广播：

代码块身份：可直接照写示例

```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)
```

说明：

- `ErrDefine` 取值：`0`=不允许错误和 NIL（两者都替换为 `ErrReplace`）、`1`=允许 NIL 不允许错误（NIL 保留，错误替换为 `ErrReplace`）、`2`=错误和 NIL 都保留原值（`ErrReplace` 不生效）
- 「错误」指输入无效（如 NIL、类型不符）；数学定义域产生的 `NAN` 结果（如 `sqrt(-1)`）不属于错误位置，任何 `ErrDefine` 档位下都不会被 `ErrReplace` 替换，本例输出保留 `NAN` 即因如此
- 不带 `ErrDefine` / `ErrReplace` 时，无效输入会直接运行报错

无效输入在不同 `ErrDefine` 档位下的替换差异：

代码块身份：可直接照写示例

```tsl
data := array(4, nil, "AAA", 9);
writeLn(tostn(sqrt(data, 0, -999)));
writeLn(tostn(sqrt(data, 1, -999)));
writeLn(tostn(sqrt(data, 2, -999)));
```

代码块身份：输出片段

```text
array(2.0,-999,-999,3.0)
array(2.0,NIL,-999,3.0)
array(2.0,NIL,"AAA",3.0)
```

说明：

- `ErrDefine=0` 把 NIL 和错误值 `"AAA"` 都替换成 `-999`
- `ErrDefine=1` 保留 NIL、只替换错误值
- `ErrDefine=2` 全部保留原值

另一个例子：

代码块身份：可直接照写示例

```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` 总是可以作为可选参数添加在最后

### 矩阵转置：反引号 `` ` ``

<!-- section-id: syntax-21-014 -->

<!-- tags: 转置, 行列互换, 翻转矩阵 -->

单次转置交换行列：

代码块身份：可直接照写示例

```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`、`&=`、`|`、`:|`

<!-- section-id: syntax-21-015 -->

<!-- tags: 拼接矩阵, 上下合并, 左右合并, 追加行 -->

`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
```

普通 `array` 的非完全矩阵：`:|` 缺位补 `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):2
```

说明：

- `union` / `&=` 用于行方向拼接
- `|` / `:|` 用于列方向拼接
- 普通 `array` 的非完全矩阵（行长度不一致）：`:|` 按原列位置对齐、缺位补 `nil`；`|` 把两行元素直接顺接（本例第 1 行变成 `(2,3,2,3)`，所以 `[1][2]` 是 `2`）
- 上述差异只适用于普通 `array`；`FMArray` 上 `|` 与 `:|` 行为一致且行数不齐时补 `0`，见 [22_fmarray.md](22_fmarray.md)
- 对应的复合赋值形式：`&=`（行并）、`|=`（列并）、`:|=`（列并补 nil）

### 列并遇到同名字符串列键

<!-- section-id: syntax-21-018 -->

<!-- tags: 同名列合并, 列被覆盖, 合并后值变了, 相同列名, 列并覆盖 -->

两侧共有的字符串列键不会并成两列，而是被右操作数覆盖：

代码块身份：可直接照写示例

```tsl
left := ones(3, array("A", "B"));
right := zeros(3, array("A", "C"));
merged := left | right;
writeLn("A:", merged[0]["A"]);
writeLn("B:", merged[0]["B"]);
writeLn("C:", merged[0]["C"]);

reversed := right | left;
writeLn("reversed A:", reversed[0]["A"]);
```

结果说明：

- `A` 输出 `0`：`A` 两侧都有，取右操作数 `right` 的值，`left` 的 `1` 被覆盖
- `B` 输出 `1`、`C` 输出 `0`：只在一侧出现的列都原样保留
- `reversed A` 输出 `1`：换序后仍是右操作数胜出，说明规则是「右侧覆盖左侧」而非「零值覆盖」
- 默认数字列下标不会触发覆盖，只有字符串列键相同才会

代码块身份：输出片段

```text
A:0
B:1
C:0
reversed A:1
```

## 默认生成模板

<!-- section-id: syntax-21-016 -->

需要矩阵构造时，优先从这个最短模板开始：

代码块身份：可直接照写示例

```tsl
matrix_value := zeros(2, 3);
```

## 决策边界和禁止项

<!-- section-id: syntax-21-017 -->

- 把 `eye(3)` 当成一维数组。
- 把 `!A` 当成逻辑非表达式。
- 把 `*` 当成矩阵乘法；矩阵乘法使用 `:*`。
- 把 `:*`、`:/`、`:\`、`:^` 当成逐元素运算；逐元素运算使用 `*`、`/`、`^`。
- 在 `:\` 左除时，右侧用一维数组而非列向量；右侧必须用 `array((v1), (v2), ...)` 形式。
- 以为 `mrows(matrix_value, 1)` 和 `mcols(matrix_value, 1)` 返回的还是数量。
- 写带步长的 `->` 时，漏掉外层 `array(...)`。
- 还在普通数组页里硬塞矩阵专用大小接口。
- 把 `::=` 写成带 `begin ... end` 的语句块。
- 用 `::` 期待遍历到任意深度；深度遍历使用 `:.`。
- 子矩阵赋值时用形状不匹配的矩阵硬塞。
- 把子矩阵赋值写在需要取值的位置，例如 `return m[:, "a"] := v;`；它求值为 `0`。
- 用 `t[:, :] := source` 重构下标时，假定它会按列名对齐；它按位置复制。
- 期待 `|` 把两侧同名字符串列键并成两列；同名键会被右操作数覆盖。
- 把 `union` 的复合赋值写成 `union=`；正确写法是 `&=`。
- 一维数组直接 `union` 期待得到二维结果；需要先对它连用两次转置前缀（双转置）变成行向量。
- 在基础函数异常参数时用分号分隔；正确写法用逗号：`sqrt(data, 1, -999)`。

代码块身份：反例 / 不可照写

```text
seq_value := 2.5, 0.5 -> 5;
```

上面这种写法不对。显式步长模式需要写成 `array(2.5, 0.5) -> 5`。
