08 Standard Library¶

本章介绍 YIAN 当前标准库(std)的主要模块、核心类型和常见用法.

标准库源码位于 lib/ 目录, 在用户代码中通常通过 std.core.*, std.collections.*, std.num.* 等路径导入.

例如:

from std.core.io import print
from std.core.string import String
from std.core.option import Option
from std.collections.hash_map import SwissTable

总览¶

标准库目前分为三大部分:

std.core: 基础 trait、容器、字符串、I/O等
std.collections: 哈希相关 trait 与哈希容器
std.num: 数值/布尔类型的扩展能力

设计上, std.core 提供了语言层面的基础抽象:

运算符重载 trait(如 Add, PartialEq, Index)
Option 与 Result 类型
迭代器抽象(Iterator, IntoIterator)
常用容器(Vec, String)

std.core¶

convert: 类型转换¶

std.core.convert 定义两种转换 trait:

pub trait From<Src> {
    static Self from(Src value);
}

pub trait Into<Dst> {
    Dst into();
}

它们是标准库约定的一种显式类型转换

接口作用说明:

From<Src>.from(value): 定义如何使用一个 Src 类型的值来构造一个 Self 类型的值, 静态函数.
Into<Dst>.into(): 定义如何将当前值转换为 Dst 类型的值, 语义上通常委托到 Dst.from(self).
实践建议: 为一种转换只维护一套语义, 避免 From 与 Into 行为不一致.

实例:

String 实现了 From<str>
str 实现了 Into<String>
u8[] 和 str 之间也实现了转换

mem: 复制与克隆¶

std.core.mem 包含:

Clone: 需要实现 clone()

基础类型(i8/i16/.../u64/f32/f64/bool/char/void)已提供 Clone 实现.

接口作用说明:

Clone.clone(): 显式复制入口, 对容器类型通常意味着深拷贝其内部数据.

ops: 运算符与比较¶

std.core.ops 是运算符重载的核心, 主要 trait 包括:

算术: Add, Sub, Mul, Div, Rem, Neg
位运算: BitAnd, BitOr, BitXor, BitNot, Shl, Shr
比较: PartialEq, PartialOrd, Ordering
索引/解引用: Index, Deref

其中 PartialEq 内置默认 ne, PartialOrd 内置 lt/le/gt/ge.

表达式章节提到的运算符重载, 本质上就是实现这里的 trait.

接口作用说明:

Add/Sub/Mul/Div/Rem/Neg: 对应算术表达式的语义, 用于自定义类型参与算术运算.
BitAnd/BitOr/BitXor/BitNot/Shl/Shr: 对应位运算与移位语义.
PartialEq.eq(rhs): 定义相等关系; ne 默认由 eq 推导.
PartialOrd.partial_cmp(rhs): 定义比较结果(Less/Equal/Greater), 并自动支持 lt/le/gt/ge.
Index.index(idx): 定义 obj[idx] 的取址规则, 通常负责边界检查.
Deref.deref(): 定义解引用行为. 参见表达式章节.

iter: 迭代器抽象¶

std.core.iter 提供:

Iterator<T>: Option<T> next()
IntoIterator<Iter>: Iter into_iter()

支持 for elem in value 的类型通常需要实现 IntoIterator.

接口作用说明:

Iterator.next(): 每次返回一个元素或 None, 是所有迭代逻辑的最小原语.
IntoIterator.into_iter(): 把容器/视图转换成迭代器, 供 for 语法统一消费.

range: 范围类型¶

std.core.range 提供 Range<T>:

pub struct Range<T> {
    pub T start
    pub T end
}

并实现:

Clone: 允许深拷贝
PartialEq: 允许使用 ==/!= 比较
Iterator<T>: 可以当作 [start, end) 的迭代器来使用
IntoIterator<Range<T>>: 允许在 for-in 循环中直接使用 Range

表达式中的 a..b 是构造 Range 的语法糖(等价于 Range(a, b))

接口作用说明:

Iterator.next(): 每次递增 start 并返回旧值, 直到 start >= end.
适用场景: 下标遍历、固定次数循环、与 Index<Range<_>> 配合切片.

option: 可选值¶

std.core.option:

pub enum Option<T> {
    None
    Some { T val }
}

接口作用说明:

is_some(): 判断是否存在值, 常用于分支保护.
is_none(): is_some 的反向判断.
unwrap(): 取出内部值; 若为 None 触发 panic.
unwrap_or(default): 为空时返回默认值, 避免 panic.
take(): 取走内部值并把当前位置置为 None, 用于“转移一次”语义.
replace(val): 用新值替换原值并返回旧值(包装为 Option), 适合原地更新.

result: 成功/错误值¶

std.core.result:

pub enum Result<T, E> {
    Ok { T val }
    Err { E msg }
}

接口作用说明:

is_ok()/is_err(): 判断结果分支, 常用于错误分流.
unwrap(): 获取成功值; 若为 Err 触发 panic.
unwrap_or(default): 出错时回退默认成功值.
unwrap_err(): 获取错误值; 若为 Ok 触发 panic.
unwrap_or_err(default): 成功时回退默认错误值.
ok(): 丢弃错误信息, 转为 Option<T>.
err(): 丢弃成功值, 转为 Option<E>.

slice: 切片工具¶

std.core.slice 为 T[] 提供:

ptr(): 取得切片首元素地址, 便于与底层内存接口互操作.
len(): 返回元素数量(不是字节数).
get(index): 安全访问, 越界返回 None.
first()/last(): 首尾元素快捷访问, 空切片返回 None.
to_vec(): 克隆切片元素得到独立动态数组.
from_raw_parts(ptr, len): 从裸指针构造切片视图, 调用方需保证地址与长度有效.
SliceIter.next(): 线性前进迭代, 到末尾返回 None.
PartialEq: 先比较长度再逐元素比较.

str: 字符串切片¶

str 是不可变字符串切片类型, std.core.str 提供:

from_slice(bytes): 把字节切片视为 str; 当前实现是位转换, 不做 UTF-8 严格校验.
as_slice(): 返回底层字节切片视图.
chars(): 按 UTF-8 解码逐字符迭代.
char_indices(): 迭代 (字节下标, 字符) 对, 便于做子串定位.
starts_with_char(c): 判断首字符匹配.
contains_char(c): 线性扫描字符是否出现.
trim(): 去除两端 ASCII 空白字符.
Index<Range<u64>, str>: 按字节区间切片并检查字符边界, 非法边界会 panic.
Hash<Murmur3Hasher>: 按字节序列写入哈希器.

string: 可变字符串¶

std.core.string 提供 String:

pub struct String {
    Vec<u8> data
}

接口作用说明:

new()/with_capacity(cap): 创建空字符串, 后者用于减少追加时扩容次数.
as_str()/as_slice(): 读取只读视图, 不转移所有权.
capacity()/len()/is_empty(): 获取容量、字节长度和空状态.
push_str(s): 追加字符串切片内容.
push(c): 以 UTF-8 编码追加单个字符.
pop(): 弹出最后一个 UTF-8 字符, 空串时返回 None.
trimmed(): 返回去空白后的新 String, 不修改原对象.
clear(): 清空内容但保留可复用缓冲区.
reserve(additional): 预留额外容量.
shrink_to_fit(): 尽量回收未使用容量.
Add 实现: 产生新字符串, 不原地修改左操作数.
Deref<str>: 允许在需要 str 的上下文中使用 String.

vec: 动态数组¶

std.core.vec 提供 Vec<T>:

pub struct Vec<T> {
    RawVec<T> raw_vec
    u64 len
}

常用方法:

构造: new(), with_capacity(cap)
访问: as_slice(), is_empty(), capacity()
修改: push, pop, insert, remove, swap_remove
扩容/收缩: reserve, shrink_to_fit, truncate, clear
合并: extend(Vec<T>), extend_from_slice(T[])

接口作用说明:

new()/with_capacity(cap): 创建空向量; 提前给容量可减少重分配.
as_slice(): 获取只读切片视图.
push(value): 尾部插入, 容量不足时自动扩容.
pop(): 尾部弹出, 空向量返回 None.
insert(index, value): 在指定位置插入并右移后续元素, index > len 会 panic.
remove(index): 删除并左移后续元素, index >= len 会 panic.
swap_remove(index): 用末尾元素覆盖被删位置, 删除更快但不保序.
reserve(additional): 预留至少 additional 个元素空间.
shrink_to_fit(): 尝试把容量收缩到当前长度.
truncate(len): 截断到给定长度.
clear(): 清空元素.
extend(other): 把另一个 Vec 的元素逐个追加.
extend_from_slice(slice): 把切片元素追加到末尾.
Index 实现: 提供下标访问, 越界 panic.
Add 实现: 拼接出新向量.

io: 输入输出与文件¶

std.core.io 提供常用 I/O 封装:

终端输出: print(str), eprint(str)
终端输入: readline()
打开文件: open_rdonly(path), open_wronly(path), open_append(path)
文件操作: read_file(path), write_file(path, content), append_file(path, content)

接口作用说明:

print(s): 写入标准输出(fd=1), 适合正常结果输出.
eprint(s): 写入标准错误(fd=2), 适合错误/诊断输出.
readline(): 从标准输入读取一行, 结果不包含换行符.
open_rdonly(path): 只读打开文件.
open_wronly(path): 写入打开, 不存在则创建, 存在则截断.
open_append(path): 追加打开, 不存在则创建.
read_file(path): 读取整个文件并返回 str.
write_file(path, content): 覆盖写入整个文件.
append_file(path, content): 在文件末尾追加写入.

fmt: 格式化相关¶

std.core.fmt 提供 ToString trait:

pub trait ToString {
    String to_string();
}

已为以下类型实现:

整数: u8/u16/u32/u64, i8/i16/i32/i64
浮点: f32/f64
bool, char, void

接口作用说明:

ToString.to_string(): 把值转换为可显示文本(String).
整数实现: 输出十进制文本.
浮点实现: 当前保留最多 6 位小数, 并处理 NaN.
bool/char/void: 分别输出 true/false、单字符和 void 文本.

raw_vec: Vec 底层缓冲¶

std.core.raw_vec 暴露了 RawVec<T>, 主要是给 Vec<T> 使用的底层存储实现:

接口作用说明:

new()/with_capacity(): 创建原始缓冲区.
ptr(): 返回底层连续内存首地址.
capacity(): 返回当前可容纳元素数.
grow(): 按策略扩容(通常翻倍).
reserve(len, additional): 基于已使用长度与新增需求进行扩容.
shrink_to_fit(len): 尝试收缩到给定有效长度.

std.collections¶

hash: 哈希 trait 与 Murmur3¶

std.collections.hash 提供:

Hasher: write(bytes), finish()
BuildHasher<T>: build_hasher()
Hash<T>: hash(hasher)

内置实现:

Murmur3Hasher
Murmur3BuildHasher

接口作用说明:

Hasher.write(bytes): 把字节流增量写入哈希状态.
Hasher.finish(): 结束计算并返回最终哈希值.
BuildHasher.build_hasher(): 为一次哈希计算创建新 hasher 实例.
Hash.hash(hasher): 类型把自身内容按约定编码到 hasher 中.
Murmur3Hasher: 默认 64 位 Murmur3 实现.
Murmur3BuildHasher: 用 seed 构造 Murmur3Hasher 的工厂.

hash_map: SwissTable¶

std.collections.hash_map 主要类型:

pub struct SwissTable<K, V, H, B> { ... }

常用方法:

构造: new(), with_capacity(cap), with_capacity_and_hasher(cap, builder)
基本操作: insert(key, value), get(key), remove(key), contains(key)
状态: len(), is_empty(), clear()

附加工具方法:

hash_key(key)
next_power_of_two(n)
calculate_growth_left(capacity)

使用要求:

K 需要可比较(==)并实现 Hash<H>
B 需要实现 BuildHasher<H>

接口作用说明:

new(): 创建空表, 使用默认 Murmur3BuildHasher.
with_capacity(cap): 按目标容量初始化, 降低早期扩容次数.
with_capacity_and_hasher(cap, builder): 自定义哈希器构建策略.
insert(key, value): 插入或覆盖键值对; 键已存在时更新 value.
get(key): 查找键并返回 Option<V>.
remove(key): 删除键对应元素(当前实现不返回被删值).
contains(key): 判断键是否存在.
len()/is_empty(): 返回元素个数与是否为空.
clear(): 清空表中元素并重置控制字节.
hash_key(key): 对单个 key 计算哈希值.
next_power_of_two(n): 计算容量对齐值.
calculate_growth_left(capacity): 计算可继续插入的负载余量.

hash_set: 哈希集合¶

std.collections.hash_set 主要类型:

pub struct HashSet<T, H, B> { ... }

常用方法:

构造: new(), with_capacity(cap), with_capacity_and_hasher(cap, builder)
基本操作: insert(value) -> bool, contains(value), remove(value) -> bool
状态: len(), is_empty(), clear()

附加工具方法:

hash_value(value)
next_power_of_two(n)
calculate_growth_left(capacity)

接口作用说明:

insert(value) -> bool: 插入新元素成功返回 true; 已存在返回 false.
contains(value): 判断元素是否存在.
remove(value) -> bool: 删除成功返回 true; 不存在返回 false.
len()/is_empty()/clear(): 读取与重置集合状态.
hash_value(value): 对元素计算哈希值.
next_power_of_two/calculate_growth_left: 容量与负载控制辅助函数.

std.num¶

数值/布尔类型的哈希支持¶

std.num 目录为以下类型提供了 Hash<Murmur3Hasher> 实现:

bool
i8/i16/i32/i64
u8/u16/u32/u64

这些实现是哈希容器(HashSet/SwissTable)可直接使用整数和布尔作为 key 的基础.

u8 ASCII 工具方法¶

std.num.u8 还额外提供了字符分类方法:

is_ascii_whitespace(): 判断空格与制表/换行等 ASCII 空白字符.
is_ascii_alpha(): 判断英文字母(A-Z 或 a-z).
is_ascii_digit(): 判断十进制数字(0-9).
is_ascii_alphanumeric(): 判断字母或数字.
is_ascii_hex_digit(): 判断十六进制字符(0-9, A-F, a-f).

这些方法在 str.trim() 等文本处理逻辑中会被使用.

常见组合用法¶

1) `String` 与 `str` 相互转换¶

from std.core.string import String

void bar() {
    String owned = String.from("hello")
    str view = owned.as_str()

    String owned2 = view.into()
}

2) `Vec<T>` 与切片 `T[]`¶

from std.core.vec import Vec

void baz() {
    Vec<i32> v = Vec<i32>.new()
    v.push(1)
    v.push(2)

    i32[] s = v.as_slice()
    Vec<i32> v2 = s.to_vec()
}

08 Standard Library¶

总览¶

std.core¶

convert: 类型转换¶

mem: 复制与克隆¶

ops: 运算符与比较¶

iter: 迭代器抽象¶

range: 范围类型¶

option: 可选值¶

result: 成功/错误值¶

slice: 切片工具¶

str: 字符串切片¶

string: 可变字符串¶

vec: 动态数组¶

io: 输入输出与文件¶

fmt: 格式化相关¶

raw_vec: Vec 底层缓冲¶

std.collections¶

hash: 哈希 trait 与 Murmur3¶

hash_map: SwissTable¶

hash_set: 哈希集合¶

std.num¶

数值/布尔类型的哈希支持¶

u8 ASCII 工具方法¶

常见组合用法¶

1) String 与 str 相互转换¶

2) Vec<T> 与切片 T[]¶

1) `String` 与 `str` 相互转换¶

2) `Vec<T>` 与切片 `T[]`¶