🎨 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:
csh
2026-07-07 16:34:19 +08:00
co-authored by Claude Fable 5
parent 23c35fdfda
commit 014c23d386
23 changed files with 2009 additions and 352 deletions
+126 -4
View File
@@ -212,6 +212,126 @@ matched := 1 in array(1, 2, 3);
row_matched := array(1, 2) sqlin array((1, 2), (3, 4));
```
### 点前缀比较算符产生逻辑数组
点前缀比较(`.=``.<>``.>``.>=``.<``.<=`)对数组/矩阵逐元素比较,返回真假值数组:
代码块身份:可直接照写示例
```tsl
a := array(0.3, 0.6, 0.9);
result := a .> 0.5;
writeLn("result[0]:", result[0]);
writeLn("result[1]:", result[1]);
writeLn("result[2]:", result[2]);
```
代码块身份:输出片段
```text
result[0]: 0
result[1]: 1
result[2]: 1
```
说明:
- `.>` 对数组的每个元素逐一比较,返回 `0`(假)或 `1`(真)
- `a .> 0.5` 返回 `array(0, 1, 1)`,对应 `0.3 > 0.5` 为假、`0.6 > 0.5` 为真、`0.9 > 0.5` 为真
- 其他点前缀比较同理:`.=`(等于)、`.<>`(不等于)、`.>=``.<``.<=`
配合 `mfind` 转换为下标数组,可用于取子集:
代码块身份:可直接照写示例
```tsl
a := array((0.3, 10), (0.6, 20), (0.9, 30));
logical_array := a[:, 0] .> 0.5;
indexes := mfind(logical_array);
subset := a[indexes];
writeLn("逻辑数组:", tostn(logical_array));
writeLn("下标数组:", tostn(indexes));
writeLn("子集行数:", mrows(subset));
writeLn("子集 (0,0):", subset[0][0]);
writeLn("子集 (0,1):", subset[0][1]);
writeLn("子集 (1,0):", subset[1][0]);
```
代码块身份:输出片段
```text
逻辑数组: array(0,1,1)
下标数组: array(1,2)
子集行数: 2
子集 (0,0): 0.6
子集 (0,1): 20
子集 (1,0): 0.9
```
说明:
- `a[:, 0] .> 0.5` 提取第 0 列并逐元素比较,得到逻辑数组 `array(0, 1, 1)`
- `mfind(逻辑数组)` 把真值位置转换成下标数组 `array(1, 2)`
- `a[indexes]` 按下标提取对应行,等价于 `select * from a where [0] > 0.5 end`
- `mfind` 的完整用法见 [22_matrix_deep_dive.md](22_matrix_deep_dive.md)
### 非完全矩阵与缺位当 0 处理
基础算符作用于非完全矩阵(行长度不一致或字符串键不对齐的数组)时,对应位置不存在或为 `nil` 时**默认当 0 处理**
代码块身份:可直接照写示例
```tsl
a := array("A": 1, "B": 1, "C": 1);
b := array("A": 2, "C": 2);
result := a + b;
writeLn("result['A']:", result["A"]);
writeLn("result['B']:", result["B"]);
writeLn("result['C']:", result["C"]);
```
代码块身份:输出片段
```text
result['A']: 3
result['B']: 1
result['C']: 3
```
说明:
- `a` 有键 `"A"``"B"``"C"``b` 只有 `"A"``"C"`
- `a + b` 时,`b["B"]` 不存在,按 `0` 处理
- 结果 `result["A"] = 1 + 2 = 3``result["B"] = 1 + 0 = 1``result["C"] = 1 + 2 = 3`
标量与矩阵的广播:
代码块身份:可直接照写示例
```tsl
matrix_value := array((1, 2), (3, 4));
result := matrix_value + 10;
writeLn("(0,0):", result[0][0]);
writeLn("(0,1):", result[0][1]);
writeLn("(1,0):", result[1][0]);
writeLn("(1,1):", result[1][1]);
```
代码块身份:输出片段
```text
(0,0): 11
(0,1): 12
(1,0): 13
(1,1): 14
```
说明:
- 标量 `+``-``*``/` 等作用于矩阵时,会广播到每个元素
- `matrix_value + 10` 每个元素都加 10
- 这些是逐元素运算(element-wise),区别于矩阵乘法 `:*`,见 [22_matrix_deep_dive.md](22_matrix_deep_dive.md)
## 本页不生成的范围
- 专门的结果集过滤函数
@@ -226,10 +346,12 @@ row_matched := array(1, 2) sqlin array((1, 2), (3, 4));
- 不要把矩阵链式比较 `::...` 和标量链式比较混写成同一种语法。
- 不要把 `in``sqlin` 当成同一个概念。
- 不要期待 `union2` 保留重复行。
- 不要用集合运算去做保留原始重复记录”的过滤任务。
- 不要把二维结果集默认当成按元素逐个比较”的集合运算。
- 左侧数组要表达这些值是否都属于右侧集合”时,用 `in`
- 左侧数组要表达这一整行是否存在于右侧结果集”时,用 `sqlin`
- 不要用集合运算去做保留原始重复记录”的过滤任务。
- 不要把二维结果集默认当成按元素逐个比较”的集合运算。
- 左侧数组要表达这些值是否都属于右侧集合”时,用 `in`
- 左侧数组要表达这一整行是否存在于右侧结果集”时,用 `sqlin`
- `minus` 表达集合差集;如果任务要求保留左侧原始重复次数,改走 [13_resultset_and_filters.md](13_resultset_and_filters.md) 的过滤规则。
- 不要在本页发明结果集过滤、TS-SQL 查询、写回语法或更大矩阵函数族。
- 不要把普通 `array(...)` 自动升级成 `FMArray`;只有任务明确命中时才进入 [23_fmarray.md](23_fmarray.md)。
- 不要把点前缀比较 `.>` 和矩阵链式比较 `::>` 混用;`.>` 返回逻辑数组,`::>` 是链式比较。
- 不要以为非完全矩阵缺位会报错;默认当 `0` 处理。