破坏性变更与迁移指南
结果化收割(哨兵 → 结果/可选)的变更公告、新旧写法对照表、机械替换禁区与迁移模板。
破坏性变更公告
语言从「哨兵返回值」向「结果/可选类型」收割是破坏性变更:函数返回类型变了,依赖旧哨兵形态的代码必须同步修改——编译器会在改动处直接报错(类型不匹配/缺守卫检查),跟着诊断走即可完成迁移。
整64(-1=未找到)改为 可选<整64>(无=未找到)。受影响 API:算法::线性查找(泛型)、算法::二分查找整32、算法::二分查找整64、映射集合::查找键位置(泛型)、映射集合::查找值位置(泛型)、正则引擎类方法 搜索/匹配或/匹配序列/贪婪循环/匹配原子。外部代码若依赖 -1 形态,按本页对照表迁移。为什么改:哨兵 -1 与合法下标值域重叠(下标 0 起但 -1 也是合法 整64)——漏判一次就是静默错值(把 -1 当下标用=越界或写坏相邻内存)。可选<整64> 从类型上分离「有值/无值」,不判 有值 直接取 值 = 编译期拒绝(见禁区一节的负例),漏检从「人工核验」升级为「类型强制」。
旧写法 → 新写法对照表
三类高频形态逐一对照。新写法遵守分支纪律:如果 + 否则 如果 显式枚举合法区间(有值 / 无值 两态各归其位),不用裸 否则 兜底。
形态一:循环内查找
旧写法(-1 哨兵·已不可编译)CN
导入 算法::{线性查找};
函数 主() -> 整32 {
整64[5] 数据 = {10, 20, 30, 40, 50};
循环 (整64 i = 0; i < 3; i++) {
整64 位 = 线性查找<整64>(数据, 5, 20 + i * 10); // 旧:-1=未找到
如果 (位 != -1) {
打印("命中 ", 位);
}
}
返回 0;
}新写法(可选 守卫分流).cnCN
导入 算法::{线性查找};
函数 主() -> 整32 {
整64[5] 数据 = {10, 20, 30, 40, 50};
循环 (整64 i = 0; i < 3; i++) {
可选<整64> 回 = 线性查找<整64>(数据, 5, 20 + i * 10);
如果 (回.有值) {
打印("命中 ", 回.值);
} 否则 如果 (!回.有值) {
打印("未命中");
}
}
返回 0;
}输出:命中 1 命中 2 命中 3
形态二:嵌套调用(外层结果喂下层实参)
旧写法(-1 直接内传·-1 会被当下标/长度静默错算)CN
整64 找30 = 线性查找<整64>(数据, 6, 30);
如果 (找30 != -1) {
整64 找20 = 二分查找整64(数据, 找30 + 1, 20); // 未找到时 -1 内传
...
}新写法(先判外层 再喂下层).cnCN
导入 算法::{线性查找, 二分查找整64};
函数 主() -> 整32 {
整64[6] 数据 = {10, 20, 30, 40, 50, 60};
可选<整64> 找30 = 线性查找<整64>(数据, 6, 30);
如果 (找30.有值) {
可选<整64> 找20 = 二分查找整64(数据, 找30.值 + 1, 20);
如果 (找20.有值) {
打印("双层命中 ", 找20.值);
} 否则 如果 (!找20.有值) {
打印("前段未命中");
}
} 否则 如果 (!找30.有值) {
打印("外层未命中");
}
返回 0;
}输出:双层命中 1
形态三:下标直用
旧写法(未找到时 -1 直作下标=越界)CN
整64 位 = 线性查找<整64>(数据, 5, 30);
打印("值=", 数据[位]); // 位=-1 时越界新写法(先判 有值 再取 值 作下标).cnCN
导入 算法::{线性查找};
函数 主() -> 整32 {
整64[5] 数据 = {10, 20, 30, 40, 50};
可选<整64> 回 = 线性查找<整64>(数据, 5, 30);
如果 (回.有值) {
打印("值=", 数据[回.值]);
} 否则 如果 (!回.有值) {
打印("未找到");
}
返回 0;
}输出:值=30
| 旧形态 | 新形态 | 说明 |
|---|---|---|
如果 (位 == -1) { … } | 如果 (!回.有值) { … } | 未找到分支(判别式取反) |
如果 (位 != -1) { 用 位 } | 如果 (回.有值) { 用 回.值 } | 命中分支(守卫授予取值权) |
数据[位](下标直用) | 先判 回.有值 再 数据[回.值] | 不判有值取值=编译期拒绝,编译器逼你分流 |
整64 位 = 查找(...) | 可选<整64> 回 = 查找(...) | 变量类型同步改(旧形态=类型错误,编译期暴露) |
「机械替换丢语义」禁区(强制人工复核)
迁移的最大陷阱不是改不完,而是机械替换改错语义。
== 比较有确定语义(-1 哨兵=空串参与比较),替换后「无值」根本没有 .值 可取,官网示例全灭(x64 4 处·靠三后端扫描穷举兜住)。机械替换只保证词面对应,不保证语义等价。语义等价人工复核——四个强制步骤
- 逐处确认旧哨兵语义:
-1在此处=未找到?空串?无效索引?不同含义对应不同的新写法分流,不能一刀切。 - 按语义选新形态:未找到→
!回.有值分支;命中→回.有值分支取回.值;比较语义→想清楚「无值时该比较的真值应该是什么」再落分支结构。 - 编译器兜底:改漏/改错处会以「缺守卫检查」或「类型不匹配」编译错误暴露——禁止用类型断言/强转绕过诊断。
- 三后端全量回归:win-x64 / linux-x86_64 / linux-arm64 全量+示例 verify 过,才算迁完。
「全后端扫描穷举声明」模板(落提交信息)
声明模板SHELL
本次迁移已对以下范围完成扫描穷举:
- 后端:win-x64 / linux-x86_64 / linux-arm64(三后端全量)
- 范围:<受影响目录/文件清单,如 website/tools/docs_data_*.py + tests/e2e>
- 形态:<旧哨兵形态逐条列出,如 == -1 / != -1 / -1 直传下标·实参>
- 结论:命中 N 处,已迁移 N 处,残留 0 处
扫描人/日期:<填写> 复核人/日期:<填写>禁区负例:不判 有值 直接取 值(编译期拒绝).cnCN
导入 算法::{线性查找};
函数 主() -> 整32 {
整64[5] 数据 = {10, 20, 30, 40, 50};
可选<整64> 回 = 线性查找<整64>(数据, 5, 30);
打印(回.值); // ✗ 编译错误:不判 有值 取 值
返回 0;
}这条编译期强制正是迁移的护栏:机械替换漏掉的语义分流,编译器会逐处拦下——红就是漏改点清单,逐红按上面四步复核即可。
受影响 API 与官网示例迁移清单
批6 变更的完整 API 面 + 官网数据同步状态(本页即清单的收口落点)。
| 模块 | 函数 | 旧签名 | 新签名 |
|---|---|---|---|
| 算法 | 线性查找(泛型) | -> 整64(-1=未找到) | -> 可选<整64> |
| 算法 | 二分查找整32 / 二分查找整64 | -> 整64 | -> 可选<整64> |
| 映射集合 | 查找键位置 / 查找值位置(泛型) | -> 整64 | -> 可选<整64> |
| 正则引擎 | 搜索 | -> 整64 | -> 可选<整64> |
| 正则引擎(内部) | 匹配或 / 匹配序列 / 贪婪循环 / 匹配原子 | -> 整64 | -> 可选<整64> |
website/tools/docs_data_*.py)扫描结论:查找族旧签名示例残留 0 处——批6 同步轮已随签名变更一并迁移(算法页/映射集合页/正则页示例全部新签名形态),本页示例为迁移后基线的实测锁面。验证命令:python website/tools/gen_docs.py --verify(全部内嵌示例编译+运行+输出比对)。注意:内建层 字符串查找 返回 -1 不属于本批范围(未收割 API·待后续批次按本页模板另行通告)。后续批次沿用此模板
结果化收割(#1360 终态立法)分批推进,每批的外部同步成本用同一模板摊销。
- 公告:本页「公告」节追加该批受影响 API 清单(旧签名→新签名一行一个);
- 对照表:新形态若超出本页三类高频形态,按同格式补「形态 N」小节(旧写法 码览 展示 + 新写法实测码块);
- 禁区自查:按「机械替换丢语义」四步执行并留全后端扫描穷举声明;
- 清单收口:官网数据扫描归零 +
gen_docs.py --verify全绿,迁移状态批注更新到批号。
已适用批次:批6(查找族·本页首批)。批2~5 及后续各批收割时直接沿用,不再另立迁移文档。