CN·语言

破坏性变更与迁移指南

结果化收割(哨兵 → 结果/可选)的变更公告、新旧写法对照表、机械替换禁区与迁移模板。

破坏性变更公告

语言从「哨兵返回值」向「结果/可选类型」收割是破坏性变更:函数返回类型变了,依赖旧哨兵形态的代码必须同步修改——编译器会在改动处直接报错(类型不匹配/缺守卫检查),跟着诊断走即可完成迁移。

#1360 批6·2026-10 通告(签名的破坏性变更)标准库查找族的返回类型从 整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> 回 = 查找(...)变量类型同步改(旧形态=类型错误,编译期暴露)

「机械替换丢语义」禁区(强制人工复核)

迁移的最大陷阱不是改不完,而是机械替换改错语义。

1427 号实证:批量机械替换把官网示例全部搞死批量把「甲 == 乙」机械替换成「甲.值() == 乙.值()」——旧形态里「无值」参与 == 比较有确定语义(-1 哨兵=空串参与比较),替换后「无值」根本没有 .值 可取,官网示例全灭(x64 4 处·靠三后端扫描穷举兜住)。机械替换只保证词面对应,不保证语义等价。

语义等价人工复核——四个强制步骤

  1. 逐处确认旧哨兵语义:-1 在此处=未找到?空串?无效索引?不同含义对应不同的新写法分流,不能一刀切。
  2. 按语义选新形态:未找到→!回.有值 分支;命中→回.有值 分支取 回.值;比较语义→想清楚「无值时该比较的真值应该是什么」再落分支结构。
  3. 编译器兜底:改漏/改错处会以「缺守卫检查」或「类型不匹配」编译错误暴露——禁止用类型断言/强转绕过诊断。
  4. 三后端全量回归: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 终态立法)分批推进,每批的外部同步成本用同一模板摊销。

  1. 公告:本页「公告」节追加该批受影响 API 清单(旧签名→新签名一行一个);
  2. 对照表:新形态若超出本页三类高频形态,按同格式补「形态 N」小节(旧写法 码览 展示 + 新写法实测码块);
  3. 禁区自查:按「机械替换丢语义」四步执行并留全后端扫描穷举声明;
  4. 清单收口:官网数据扫描归零 + gen_docs.py --verify 全绿,迁移状态批注更新到批号。

已适用批次:批6(查找族·本页首批)。批2~5 及后续各批收割时直接沿用,不再另立迁移文档。