标准库导览

在前二十章中，你学习了 Auto 的核心语言：类型、函数、模式匹配、泛型、错误处理、 并发和元编程。但一门语言的价值取决于它开箱即用提供了多少工具。Auto 附带了一个 全面的标准库——一个包含各种现成模块的工具箱，涵盖每个程序都需要的功能：字符串、 数学、文件 I/O、集合、时间和 JSON。

本章是一次导览。我们将按领域逐一介绍标准库中最实用的部分，并配有实际的代码示例。 把它想象成一次井然有序的车间参观：你不需要记住架子上每一个工具的位置，但你会 知道需要时去哪里找。

字符串工具

字符串无处不在。解析用户输入、格式化日志消息、构建文件路径——大多数程序都有 相当一部分时间在处理文本。Auto 的 std::string 模块为 String 类型提供了丰富 的方法集。

核心函数包括：trim() 用于去除空白，format!() 用于插值格式化，split() 用于拆分字符串，join() 用于合并，以及查询方法如 contains()、starts_with() 、ends_with()、to_upper()、to_lower() 和 replace()。

字符串处理流水线：trim、format、split、join 和查询

注意每种语言如何实现相同的操作：

操作	Auto	Rust	Python	C	TypeScript
去除空白	.trim()	.trim()	.strip()	手动循环	.trim()
格式化字符串	format!()	format!()	.format()	sprintf	模板字面量
拆分	.split(",")	.split(",")	.split(",")	strtok	.split(",")
合并	.join(" ")	.join(" ")	" ".join()	手动循环	.join(" ")
包含	.contains()	.contains()	in 运算符	strstr	.includes()

Auto 的版本与 Rust 高度相似，这是有意为之的。如果你熟悉 Rust 的标准库，那么你 已经掌握了 Auto 的大部分 API。

数学与数值

std::math 模块提供了常用的数学函数。大多数是顶层函数，可以直接调用：min、 max、abs、round、floor、ceil、clamp、pow 和 sqrt。

这些是进行计算时常用的函数——从评分算法到物理模拟再到金融计算。

数学运算：min、max、abs、round、clamp、pow、sqrt

几点说明：

1. clamp(value, lo, hi) 将值约束在一个范围内。clamp(15, 0, 10) 返回 10 ，因为 15 超过了上限。这个函数出人意料地有用——UI 代码中保持滑块在边界内、 游戏物理中限制速度、数据验证中等场景都会用到。

2. round、floor、ceil 处理小数部分的方式不同。round(3.7) 得到 4 （四舍五入到最近的整数）。floor(3.9) 得到 3（向负无穷方向取整）。 ceil(3.1) 得到 4（向正无穷方向取整）。

3. 在 Rust 和 C 中，min 和 max 位于不同的地方。Rust 把它们放在 std::cmp 中，C 则使用三元运算符或宏。Python 和 TypeScript 分别以内置函数和 Math 方法提供。Auto 为了方便，将它们作为顶层函数提供。

IO 与文件操作

读写文件是程序最常做的事情之一。Auto 的 std::fs 模块提供了文件 I/O、路径 操作和目录操作相关的函数。这些函数使用 !T（结果类型）进行错误处理，所以你 永远不会忘记处理失败情况。

核心函数包括：read_file、write_file、path_join、exists、mkdir、 list_dir、copy 和 remove。

文件 I/O：读取、写入、路径操作和目录列表

关键观察：

1. path_join("data", "output.txt") 使用当前平台的正确分隔符（Unix 上是 / ，Windows 上是 \）构建路径。你应该始终使用 path_join 而不是用 / 拼接 字符串——这样可以防止在不同操作系统上运行时出现 bug。

2. read_file 和 write_file 将整个文件内容作为字符串处理。在 Rust 中， 它们是 fs::read_to_string 和 fs::write。在 C 中，你需要手动使用 fopen /fread/fwrite 并管理缓冲区。Auto 抽象了缓冲区管理的细节。

3. exists 返回 bool——如果文件不存在不会报错，只是返回 false。这让 检查操作变得很简单。

4. mkdir 创建嵌套目录（类似 mkdir -p）。如果目录已经存在，它不会报错， 而是静默跳过。

集合工具

你在第 19 章学习了迭代器及其可链式调用的方法。std::collections 模块为 List<T>、Map<K,V> 和 Set<T> 添加了更多操作：sort、reverse、 unique、flatten、zip、chunk、take 和 skip。

这些辅助函数在数据处理中非常常用，将它们内置在标准库中可以省去你重复造轮子 的麻烦。

集合操作：sort、reverse、unique、flatten、zip 和 chunk

这些操作值得仔细分析：

1. .sort() 返回一个新的已排序列表，原始列表不变。默认排序顺序是升序。你 可以传入比较器闭包来自定义排序：nums.sort(fn(a, b) int { b - a }) 实现 降序排列。

2. .unique() 去除重复元素，同时保持插入顺序。每个元素的第一次出现被保留。 当你需要保持顺序时，这比 Set 更有用。

3. .flatten() 将列表的列表变成单个列表。[[1, 2], [3, 4], [5, 6]].flatten() 变成 [1, 2, 3, 4, 5, 6]。这是 .chunk() 的逆操作。

4. .zip() 将两个列表组合成对列表。names.zip(scores) 生成 [("Alice", 95), ("Bob", 87), ("Carol", 92)]。如果两个列表长度不同， zip 会在较短的列表处停止。

5. .chunk(3) 将列表分成最多 3 个元素一块。如果列表长度不是 3 的倍数， 最后一块可能更小。

时间与日期

处理日期和时间是出了名的棘手。时区、闰年、夏令时——到处都是边界情况。Auto 的 std::time 模块提供了坚实的基础：获取当前时间、格式化日期、解析日期字符串和 计算时间间隔。

核心类型是 Time（时间点）和 Duration（时间段）。核心函数包括 Time.now() 、.format()、Time.parse()、Duration.hours()、Duration.minutes() 和 Duration.seconds()。

时间操作：当前时间、格式化、解析和时间间隔运算

几点说明：

1. 格式说明符 -- Auto 使用与 C 的 strftime 和 Rust 的 chrono 相同的 %Y-%m-%d %H:%M:%S 格式字符串。%Y 是四位年份，%m 是零填充的月份， %d 是零填充的日期，%H 是 24 小时制的小时，%M 是分钟，%S 是秒。

2. 时间间隔运算 -- Duration.hours(2) + Duration.minutes(30) 创建一个 2.5 小时的时间间隔。你可以将时间间隔加到时间上（now + duration），也可以 用时间相减得到时间间隔（later - now）。

3. total_minutes() 将时间间隔转换为其总分钟数，不管它是如何构造的。类似地， total_seconds() 返回总秒数。

4. Time.parse() 是 .format() 的逆操作。它接受一个字符串和一个格式说明符， 返回一个 Time。如果字符串与格式不匹配，则返回错误（!Time）。

JSON 序列化

JSON 是 Web 的通用语言。API 发送它，配置文件存储它，日志写入它。Auto 的 std::json 模块提供了 to_json 和 from_json 函数，可与任何实现了 Serialize 和 Deserialize spec 的类型一起使用。

JSON 序列化：在类型与 JSON 之间转换

让我们分析一下发生了什么：

1. to_json(alice) 将 User 值序列化为 JSON 字符串： {"name":"Alice","age":30,"email":"alice@example.com"}。to_json 函数 可与任何实现了 Serialize spec 的类型一起使用。

2. from_json!(json, User) 将 JSON 字符串反序列化回 User 值。from_json! 中的 ! 表示这可能失败——如果 JSON 格式错误或缺少必需字段，它返回错误。 在实践中，你应该用 ? 或 match 来处理。

3. to_json_pretty(alice) 产生相同的 JSON，但带有缩进以便人类阅读。这在 配置文件和调试中很有用。

4. 集合自然地序列化 -- List<User> 变成 JSON 对象数组，Map<String, Int> 变成 JSON 对象，以此类推。序列化是递归的，可以处理任意深度的嵌套。

在 Rust 中，这由 serde 和 serde_json 驱动，它们是序列化事实上的标准。在 Python 中，这是内置的 json 模块。在 TypeScript 中，是 JSON.stringify 和 JSON.parse。在 C 中，通常需要第三方库如 cJSON，不过这里我们展示了简单的 sprintf 实现。

使用外部依赖的 JSON 序列化

TOML 配置

TOML 是一种流行的配置格式，在 Rust 生态系统中尤其如此（它是 Cargo.toml 使用的格式）。Auto 的 std::config 模块提供了 parse_toml 函数，用于将 TOML 配置文件读取为结构化数据。

TOML 配置解析

TOML 解析返回嵌套的映射结构。在 Auto 中，你可以使用索引语法访问值： config["server"]["host"]。在 Rust 中，这映射到嵌套的 HashMap。Python 3.11+ 在标准库中提供了 tomllib。C 没有内置的 TOML 支持，需要使用 tomlc99 等第三方库。

数据编码

将二进制数据编码为文本对于网络协议、文件格式和数据存储至关重要。Auto 提供了 base64_encode/base64_decode 和 hex/unhex 函数来处理两种最常见的 二进制到文本编码。

Base64 编码与解码

十六进制编码与解码

关于数据编码的要点：

1. Base64 将 3 个字节编码为 4 个 ASCII 字符。它用于邮件附件、数据 URL 和 JWT 令牌。每种语言的标准库或常用 crate 中都有 base64 库。

2. 十六进制编码 将每个字节转换为两个十六进制字符（0x00-0xFF）。它是 人类可读的，常用于哈希摘要、网络地址和调试输出。hex 函数同时支持字节数组 和整数。

3. Auto 的编码函数 同时处理字符串和字节数组。b"..." 是 Auto 中的字节字面量 （等同于 Rust 的 b"..."）。

计时与性能

测量操作耗时是性能测试和性能分析的基础。Auto 提供了 now() 获取当前时间戳 和 sleep() 暂停执行。

测量经过时间

注意不同平台测量时间的方式：

1. Auto 使用 now() 返回时间戳，sleep(ms) 用于延迟。两个时间戳相减得到 经过的毫秒数。

2. Rust 使用 Instant::now() 配合 .elapsed().as_millis() 进行精确测量， thread::sleep() 用于延迟。

3. C 使用 <time.h> 中的 clock() 配合 CLOCKS_PER_SEC 转换。

4. TypeScript/JavaScript 使用 Date.now() 返回自纪元以来的毫秒数。

正则表达式

正则表达式是文本搜索和替换的强大工具。Auto 通过 use.rust FFI 机制集成 Rust 的 regex crate，让你可以使用快速、安全的正则表达式引擎。

正则表达式搜索与替换

这个正则表达式示例展示了 Auto 对 Rust crate 的 FFI 支持：

1. use.rust regex::Regex 从 Rust 的 regex crate 导入 Regex 类型。.rust 限定符告诉 Auto 使用原生的 Rust 依赖。

2. c"\\d+" 是 Auto 中的原始字符串字面量（等同于 Rust 的 r"\d+"）。反斜杠 不会被当作转义字符处理。

3. .unwrap() 处理正则表达式模式可能无效的情况。在生产代码中，你应该使用 ? 或 match 进行适当的错误处理。

4. .replace_all() 替换每个匹配项，而不仅仅是第一个。要只替换第一个，使用 .replace()。

密码学

Auto 通过 Rust 的 crate 生态系统提供密码学原语。sha2 crate 提供了 SHA-256 和其他哈希函数。

SHA-256 哈希摘要

dep sha2 声明告诉 Auto 的包管理器将 sha2 crate 作为依赖引入。结合 use.rust sha2::Sha256，你可以直接使用生产级的密码学库。

高级数学

除了基本的 min、max 和 sqrt 函数外，Auto 还通过数值类型的方法支持 高级数学运算：.powf()、.abs()、.sin()、.cos() 等。

高级数学：幂运算、三角函数和绝对值

Auto 中的数值方法与 Rust 的 f64 方法高度一致：

1. .powf(y) 计算幂：2.0.powf(3.0) = 8.0。
2. .sqrt() 计算平方根：2.0.sqrt() ≈ 1.4142。
3. .abs() 返回绝对值：(-5.0).abs() = 5.0。
4. .sin() 和 .cos() 计算三角函数，参数为弧度。

总结

本章导览了 Auto 标准库中最实用的部分：

领域	模块	核心函数
字符串	std::string	trim、format!、split、join、contains、replace
数学	std::math	min、max、abs、round、floor、ceil、clamp、pow、sqrt、powf、sin、cos
文件 I/O	std::fs	read_file、write_file、path_join、exists、mkdir、list_dir
集合	std::collections	sort、reverse、unique、flatten、zip、chunk
时间	std::time	Time.now、.format、Time.parse、Duration.hours、Duration.minutes、now、sleep
JSON	std::json	to_json、from_json、to_json_pretty
TOML	std::config	parse_toml
编码	std::encoding	base64_encode、base64_decode、hex、unhex
正则表达式	regex crate	Regex.new、.replace_all、.replace
密码学	sha2 crate	Sha256.new、.update、.finalize、.hex

核心要点：

1. Auto 开箱即用 -- 标准库涵盖了最常见的编程任务。你很少需要为基本操作 引入外部包。

2. API 一致性好 -- .sort()、.trim()、.format() 等方法遵循可预测的 命名约定。如果你能猜到函数名，它很可能就存在。

3. 错误处理内置 -- 文件 I/O 和 JSON 解析使用 !T 结果类型，所以错误在 调用处是显式的，并被妥善处理。你永远不会静默地忽略一个失败。

4. 相同的概念适用于所有目标语言 -- Auto 的标准库自然映射到 Rust 的 std

   • serde、Python 的内置模块、C 的 stdlib + POSIX，以及 TypeScript 的 fs/path/JSON。学习 Auto 的标准库同时也教会你每个目标平台的惯用方式。

5. 这趟导览只是开始 -- 完整的标准库还包括网络、加密、正则表达式、并发 原语等更多内容。请访问 docs.auto.dev 查看完整文档。

这是毕业设计之前的最后一个常规章节。你现在拥有完整的工具箱：类型系统、模式匹配、 泛型、错误处理、闭包、迭代器、并发、元编程，以及一个全面的标准库。在下一章中， 你将把所有这些整合起来，构建一个真实的项目。