标准库全景

本章导读

很多语言把"标准库很大"当成学习负担，xlang 反过来：标准库的用法你早就会了——第 5 章的 print、第 18 章的 string.split、第 20 章的 time.now()，全是标准库成员。本章要做的是三件事。一，讲透设计哲学：为什么不需要 import（默认注入），为什么 math 直通 CRT 而 time 走 XRT（XRT 优先原则），为什么没用到的函数不进你的可执行文件（按需注入，有 cgen 证据）。二，给全地图：33 个命名空间加全局 4 函数，每个多少函数、什么定位、哪章讲过，一张表查一辈子。三，补讲重点模块：math 的 34 个函数批量实测，random 的种子复现，hash 的 8 个变体，codec/encoding 的编解码对，log 的级别系统，json/xson 的往返，os/signal 的进程信息与信号处理，以及压轴的 tcc 模块——脚本里编译 C 源码跑出真 exe。读完你将获得一项元技能：会自己读标准库源码（36.10），从此不再依赖文档更新速度。

36.1 设计哲学

四条原则全部来自 docs/标准库设计.md，并且都能用编译器实测验证。

一，默认注入，免 import 免 extern。"DEMO6 标准库默认进入 xlang 编译环境，用户不需要为基础能力手写 extern 或 import。"与第 35 章的扩展库形成分工：标准库是"每行代码都可能用"的基础能力，默认可得；扩展库是按需引入的专业能力，import 显式声明。

二，XRT 优先。"能够由 XRT 提供的能力，必须优先映射到 XRT；确实属于 CRT 基础设施、没有必要在 XRT 重复实现的能力，可以直接映射到 CRT。典型例子是 math 命名空间。"所以 time/file/json 走 XRT（跨平台一致行为），math 走 CRT（sin/sqrt 没有重造轮子的理由）。

三，按需注入。编译器只为实际用到的标准库函数注入 extern 声明。实测一个只用了 math.sqrt 的程序，生成 C 里就一条声明、一次直调：

double sqrt(double x);        // ← 唯一注入的数学声明
// 调用处：xvoCreateFloat((double)(sqrt(2.0)))

math.sqrt 展开后就是裸的 CRT sqrt——零包装、零开销，没用到的 500 多个函数连名字都不出现在产物里。

四，字符串所有权统一桥接。XRT 函数返回的需要 xrtFree 的堆字符串，由标准库薄封装统一调 take_cstr 复制进临时内存区后立即释放原指针——你拿到的永远是普通 string，"用户不需要也不能手动释放"（深入细节 2 展开）。

顺带一个反直觉事实：print 家族不经过 CRT 的 stdout——Windows 下生成代码直接用 WinAPI 标准输出句柄写入，POSIX 下用 write(1, ...)，连 stdio.h 都不包含。这就是为什么 print 在混编场景永远没有缓冲刷新问题。

36.2 全景地图

本章对 src/stdlib/xl6_stdlib_data.c 注册表做了全量统计：515 个公开函数（唯一名）、115 个常量、33 个命名空间加全局。一表看全（函数数为唯一名计数，已讲章节给出回链）：

读表三式：按任务查（要压缩去 codec，要日志去 log，要唯一 ID 去 id）；按章节回（已讲章节有系统讲解，未讲的以 stdlib.html 参考页为准）；按源码验证（36.10 的方法，任何函数的精确签名一分钟查清）。注意一个口径说明：功能清单文档写的还是"488 函数/105 常量"的旧数，本章的 515/115 是对注册表源码的实时统计——标准库在生长，以注册表为准（深入细节 3）。

36.3 math：CRT 直通

34 个函数分五族，全部批量实测通过。常量 5 个（pi/tau/e/nan/inf），在重写阶段直接替换为字面量，连函数调用都不发生：

三个使用要点。一，参数返回统一 float（int 实参自动提升），唯 math.abs 有 int 重载保持整数。二，round 是编译器辅助实现（内部用 floor/ceil 组合），不是 CRT round——跨平台行为一致。三，nan/inf 是字面量常量，配合 isNaN/isInf 做防御：if math.isNaN(x) then ...。

36.4 random 与 hash

random 只有 5 个函数，但有两个关键词：seed(seed, seq) 双参数与可复现：

random.seed(uint64(2026), uint64(1))
print(random.u32())              // 831089821
random.seed(uint64(2026), uint64(1))   // 同种子同序列
print(random.u32())              // 831089821 —— 完全复现
print(random.range(1, 6))         // 1..6 闭区间整数
print(random.string(8))           // "1bQptd-0" 类随机串
print(random.string(6, "ABC"))    // 限定字符集，如 "BCAAAC"

同 seed 同 seq 给出完全相同的序列——测试与模拟场景的刚需；要不可预测就不调 seed（线程种子自动初始化）。需要多个独立流时用第 34 章见过的 Random native class：Random(uint64(42), uint64(1)) 每个实例一条流，官方示例验证过同参数两实例逐值相等。hash 的 8 个函数是非加密哈希（校验、分桶、指纹用）：u32/u64 两宽度，Micro/Nano 两精度变体，WithSeed 三加盐版本：

print(int(hash.u32("hello")))                 // 1360413475
print(int(hash.u32("world")))                 // 1567078908 —— 输入变则哈希变
print(int(hash.u32WithSeed("hello", uint32(7))))  // 1956780885 —— 加盐变体

注意 int(...) 转换不能省——当前版本直接 print uint32/uint64 值会在链接期失败（坑 3，本章记录的编译器问题）。加密级哈希（SHA 家族）在 crypto 命名空间，别用 hash 做密码学用途。

36.5 codec 与 encoding

codec 是"字节↔文本"的三对编解码加一个百分号变体，全部成对实测：

print(codec.base64Encode("hello"))     // aGVsbG8=
print(codec.base64Decode("aGVsbG8="))  // hello —— 往返一致
print(codec.hexEncode("hi"))          // 6869
print(codec.hexDecode("6869"))        // hi
print(codec.formUrlEncode("a b+c"))   // a+b%2Bc —— 表单风格（空格变 +）
print(codec.percentEncode("中文"))     // %E4%B8%AD%E6%96%87 —— UTF-8 逐字节转义

每对都有 Bytes 变体（base64EncodeBytes 等）操作 Buffer。formUrl 与 percent 的差异就在空格：表单约定 +，纯百分号约定 %20。encoding 管更大的世界——字符集检测、命名、UTF 互转：

print(encoding.isUtf8("中文"))             // true
int cs = encoding.detect("hello")
print(encoding.name(cs))                  // "utf-8"
print(encoding.charSize(cs))              // 1 —— 该字符集最小单元字节数
Buffer b = encoding.encodeUtf8("你好")
print(b.len())                           // 6 —— 两汉字各 3 字节
print(encoding.decodeUtf8(b))            // 你好 —— 往返一致

UTF-16/32 各有 LE/BE 的 encode/decode 四件套加字节序交换函数，9 个字符集常量（encoding.utf8/utf16/bom/autoDetect 等）配合 convertBytes 做任意字符集间转换。中文 Windows 上读老系统 GBK 文件时，convertBytes 就是你的翻译官。

36.6 log 日志系统

16 函数 + 10 常量构成完整日志系统：六个级别（trace/debug/info/warn/error/fatal）、三个输出目标（控制台/文件/滚动文件）、三种格式（text/simple/json）。默认开箱即用——带时间戳、线程号、颜色：

log.info("info msg")
2026-07-19 06:43:01 [INFO ] [tid=23340] [:0 ] info msg
log.warn("warn msg")
2026-07-19 06:43:01 [WARN ] [tid=23340] [:0 ] warn msg（黄色）

级别控制实测：默认级别是 info（trace/debug 被压掉），setLevel 动态调整，getLevel/levelName 可回读：

log.setLevel(log.warnLevel)
log.info("you should not see this")   // 被级别压制，无输出
log.warn("warn after level set")      // 正常输出
print(log.levelName(log.getLevel())) // WARN

常量分两组：级别常量 traceLevel(0) 到 offLevel(6)，格式常量 textFormat/simpleFormat/jsonFormat。生产用法是 create + addFile/addRollingFile 定制自己的 Logger 实例（滚动文件按大小切分，长期运行的服务必备），flush 强制落盘。log.write 是底层入口（自定义级别与格式串）。相比 print 调试法，log 给了你级别开关——上线后把 setLevel 提到 warn，调试输出一行不用删。

36.7 json 与 xson

json 7 函数覆盖解析/生成/校验/文件/流式，实测往返：

var v = json.parse("{\"name\": \"xlang\", \"version\": 6, \"tags\": [\"a\", \"b\"]}")
print(v["name"])             // xlang —— parse 结果是动态容器，下标直取
print(v["version"])          // 6
print(json.valid("{bad json")) // false —— 先校验再解析的好习惯
print(json.stringify(v))     // {"name":"xlang","version":6,"tags":["a","b"]}

文件对 read/write 免手工 IO，stringify/write 的 pretty 参数控制美化；visit 是流式遍历大 JSON 的回调入口（配合 visitComplete/visitStopped/visitInvalid 三个常量判结果），writer 是增量构造器。与 derive json（第 25 章）的分工：derive 处理"已知类型的 class 实例序列化"，json.parse/stringify 处理"结构未知或动态的 JSON 数据"——两者底层同一 XRT 引擎。xson 是 xlang 扩展记法，8 函数与 json 对应（多一个 options 构造 XsonOptions），list/set 这类 JSON 表达不了的容器走 xson：

var d = dict{"a": 1, "b": 2}
string text = xson.stringify(d)
print(text)                     // {"a":1,"b":2}（此例恰与 JSON 同形）
print(xson.valid(text))         // true
var back = xson.parse(text)
print(back["a"])               // 1 —— 往返一致

36.8 os 与 signal

os 回答"我在哪、我是谁"：

print(os.platform())                // "windows"
print(os.env("USERPROFILE") != "")  // true —— 环境变量读取
print(os.args().length >= 0)       // true —— 命令行参数数组

其余成员：cwd/setCwd 当前目录、exec/run/start 系执行外部程序（重型任务走 process 命名空间的管道族）、chain 串接命令。signal 是控制台信号的统一抽象，7 个常量覆盖跨平台交集：INT/TERM/HUP 是 Unix 老朋友，BREAK/CLOSE/LOGOFF/SHUTDOWN 是 Windows 控制台事件——同一套 API 两边跑。官方回归用例展示了完整四件套：回调注册（on/once）、channel 路由（sendTo）、任务组取消（cancelOn）、手工触发（raise）：

int hits = 0
func(var) onInt = func(var event)
    hits = hits + int(event["code"])
end

SignalHandle direct = signal.on(signal.INT, onInt)
channel<var> events = channel::<var>(2)
SignalHandle routed = signal.sendTo(events, signal.INT)  // 信号进 channel

signal.raise(signal.INT)          // 手工触发（测试用）
// → 回调执行、channel 收到 {"code", "name"} 事件
signal.count(signal.INT)          // ≥ 1
signal.received(signal.INT)       // true
direct.close()                     // SignalHandle 用完即关
signal.restore(signal.INT)         // 恢复默认处理

实战意义：命令行工具用 signal.on(signal.INT, ...) 把 Ctrl+C 变成"优雅退出"（落盘、关连接）；测试用 signal.raise 自触发验证处理逻辑；sendTo 把信号并入第 29 章的 channel 事件循环，cancelOn 把信号接到第 31 章的 TaskGroup 上做整组取消。

36.9 tcc：脚本内编译 C

本章彩蛋。xl.exe 内嵌了完整 TCC（第 1 章讲过 xlang 本身靠它编译），tcc 命名空间把这套能力直接开放给脚本——运行期编译 C 源码并执行：

func main(...)
    string code = "#include <stdio.h>\nint main(void){ puts(\"hello from embedded C\"); return 42; }\n"
    int rc = tcc.run(code)
    println("rc =", rc)
end

// 输出：
// hello from embedded C      ← C 程序的 puts 直接打到控制台
// rc = 42                    ← C main 的返回值成为 tcc.run 的返回值

还能编译成真实可执行文件——tcc.compile(源码, 输出路径, 模式)：

int rc2 = tcc.compile("int main(void){ return 0; }\n", "tcc_out.exe", tcc.EXE)
# compile rc = 0 —— 磁盘上多出 3 KB 的 tcc_out.exe，可独立运行

7 个函数分三组：run/runFile（内存编译执行）、compile/compileFile（产出文件，5 个模式常量 MEMORY/EXE/OBJ/DLL/PREPROCESS 可组合）、vfsMount/vfsClear（往编译用虚拟文件系统挂载动态生成的源码，配 runFile/compileFile 用）。Context 创建独立的 TccContext 实例做细粒度控制（加 include 路径、定义宏）。姊妹模块 xlang（3 函数：Context/run/runFile）同理运行 xlang 脚本——xlang 解释执行 xlang。应用场景：插件系统（用户提交 C 热代码）、教学演示（本书这种）、构建脚本里的代码生成器、运行时 JIT 式的热点下沉。安全提示是常识：tcc.run 执行的是任意 C，别编译不可信来源的代码。

36.10 自助阅读源码

标准库的全部真相在一个文件里：src/stdlib/xl6_stdlib_data.c（约 7700 行，随源码发布）。结构从上到下一目了然：

查询套路：想知道 encoding.charSize 怎么用时，先 grep 注册表找到 {"encoding", "charSize", ...} 一行，记下函数体名 xl6StdEncodingCharSizeBody，再跳到函数体——发现它接 int charset 而非 string（坑 4 就是这么查清的）。914 条注册项 = 515 个唯一公开函数 + 重载 + 内部桥接层（__xrt_string/__xrt_time/__xl_runtime 等下划线命名空间不直接对你开放，是标准库自己的施工脚手架）。

深入细节

⚠️ 常见错误

    print(math.squrt(2.0))     // ← 报错（第 2 行）：squrt 拼写

bad.xl:2:16: [stdlib] standard library namespace has no such symbol

    print(math.sqrt("hello"))   // ← 报错（第 2 行）

bad.xl:2:21: [sem] 函数调用实参类型和参数类型不匹配: target float, value string

    print(hash.u64("hello"))    // 编译过，链接炸：

tcc: error: unresolved reference to 'xl6_xrt_u64_to_string'

    print(encoding.charSize("中"))   // ← 报错（第 2 行）

bad.xl:2:29: [sem] 函数调用实参类型和参数类型不匹配: target int, value string

<string>:2: error: missing terminating " character
// tcc.run returned -1 —— C 编译失败

本章小结

复习题

1. 标准库为什么不需要 import？math.sqrt(2.0) 在生成的 C 里变成什么（提示：一条声明一次直调）？
2. "XRT 优先"原则的含义是什么？math 为什么是 CRT 直通的典型例外？
3. random.seed 需要几个参数？同参数两次 seed 后 u32 序列有什么性质？直接 print random.u32() 会遇到什么问题、怎么绕行？
4. log 的默认级别是什么？setLevel(log.warnLevel) 之后 info/warn 各自的命运？
5. tcc.run 与 tcc.compile 的区别是什么？tcc.run 的返回值来自哪里？

编程练习