标准库规范

本文件定义 YaoXiang 编程语言的标准库规范，包括核心库、IO库和数学库。

第一章：核心库

1.1 基础类型

标准库提供以下基础类型的实现：

类型	模块	说明
`Option(T)`	`std.option`	可选值类型
`Result(T, E)`	`std.result`	错误处理类型
`List(T)`	`std.collection`	动态数组
`Map(K, V)`	`std.collection`	哈希映射
`String`	`std.string`	字符串类型
`Array(T, N)`	`std.array`	固定大小数组

1.2 Option 类型

Option: (T: Type) -> Type = { some: (T) -> Option(T), none: () -> Option(T) }

变体构造：

变体	语法	说明
`Option.some`	`Option.some(value)`	有值
`Option.none`	`Option.none()`	无值

常用方法：

yaoxiang

// 检查是否有值
is_some: (self: Option(T)) -> Bool
is_none: (self: Option(T)) -> Bool

// 获取值（可能 panic）
unwrap: (self: Option(T)) -> T

// 获取值或默认值
unwrap_or: (self: Option(T), default: T) -> T

// 映射值
map: (R: Type) -> ((self: Option(T), f: (T) -> R) -> Option(R))

1.3 Result 类型

Result: (T: Type, E: Type) -> Type = { ok: (T) -> Result(T, E), err: (E) -> Result(T, E) }

变体构造：

变体	语法	说明
`Result.ok`	`Result.ok(value)`	成功值
`Result.err`	`Result.err(error)`	错误值

常用方法：

yaoxiang

// 检查是否成功
is_ok: (self: Result(T, E)) -> Bool
is_err: (self: Result(T, E)) -> Bool

// 获取值（可能 panic）
unwrap: (self: Result(T, E)) -> T

// 获取值或默认值
unwrap_or: (self: Result(T, E), default: T) -> T

// 映射成功值
map: (R: Type) -> ((self: Result(T, E), f: (T) -> R) -> Result(R, E))

// 映射错误值
map_err: (F: Type) -> ((self: Result(T, E), f: (E) -> F) -> Result(T, F))

Error 载体与错误码（#323 M4）：

std 各模块的 Err 载体 Error 携带规范化错误码，码复用 RFC-013 的 E6xxx/E7xxx 段位（如 E6009 = Range 步长非法），为跨版本稳定契约——程序可按码编程判定，yx explain E6009 可查文档。码索引见 RFC-013「运行时错误值与码贯通」章节。

yaoxiang

// Error 值形态：{ code: String, message: String }

// 取出 Err 载体（Ok 时报运行时错误）
unwrap_err: (T, E) -> ((self: Result(T, E)) -> E)

// 读取错误码 / 消息
code: (self: Error) -> String
message: (self: Error) -> String

按码判定示例：

yaoxiang

use std.range
use std.result

r = range.iter(1..10..0)      // step=0 → Err(Error)
if result.is_err(r) {
    e = result.unwrap_err(r)
    if result.code(e) == "E6009" {
        // 按 Range 步长非法分支处理
        io.println(result.message(e))
    }
}

用户自定义错误建模走 Result(T, E) 的 E 泛型参数（自定义变体集），std Error 是便捷兜底载体，其码体系不约束用户 E 类型。

1.4 错误传播

ErrorPropagate ::= Expr '?'

? 运算符自动传播 Result 类型的错误：

// 成功时返回值，失败时向上返回 err
data = fetch_data()?

// 概念等价形式（注意：变体解构 match 尚未落地——RFC-010b 交付前
// 会报编译错误 E3008，`?` 是当前唯一可用的错误传播写法）
data = match fetch_data() {
    ok(v) => v
    err(e) => return err(e)
}

1.5 断言（std.assert）

std.assert 模块提供统一的断言机制——运行时 assert 和编译期精化类型 Assert 是同一原语的两面。

yaoxiang

// IsTrue：值到类型的桥接函数
IsTrue: (b: Bool) -> Type = match b {
    true => Void,      // ⊤，程序继续
    false => Never,    // ⊥，发散
}

// Assert：编译期精化类型原语
Assert: (cond: Bool) -> Type = IsTrue(cond)

// assert：运行时断言（Assert 的值引入子）
assert: (cond: Bool, ?msg: String | Error) -> Assert(IsTrue(cond))

// Result 重载
assert: (result: Result) -> Assert(IsTrue(is_ok(result)))

dispatch 分派：

条件	行为
cond 的所有自由变量编译期已知	编译器求值，true → 擦除，false → 编译错误
存在运行时自由变量	插入运行时 check，注入流敏感假设集 Γ

assert(false, "msg") 等价于 raise——不需要单独的 throw/raise 关键字。

第二章：IO 库

2.1 标准输入输出

yaoxiang

// 标准输出
print: (msg: String) -> Void
println: (msg: String) -> Void

// 标准输入
read_line: () -> String
read_char: () -> Char

2.2 文件操作

yaoxiang

// 文件类型
File: Type = {
    path: String,
    read: (self: File) -> Result(String, Error),
    write: (self: File, content: String) -> Result(Void, Error),
    append: (self: File, content: String) -> Result(Void, Error),
    close: (self: File) -> Void
}

// 文件操作
open: (path: String) -> Result(File, Error)
create: (path: String) -> Result(File, Error)
delete: (path: String) -> Result(Void, Error)

2.3 目录操作

yaoxiang

// 目录类型
Dir: Type = {
    path: String,
    entries: (self: Dir) -> Result(List(String), Error),
    create: (self: Dir) -> Result(Void, Error),
    delete: (self: Dir) -> Result(Void, Error)
}

// 目录操作
read_dir: (path: String) -> Result(Dir, Error)
create_dir: (path: String) -> Result(Void, Error)
delete_dir: (path: String) -> Result(Void, Error)

第三章：数学库

3.1 基础数学函数

yaoxiang

// 绝对值
abs: (x: Int) -> Int
abs: (x: Float) -> Float

// 最大最小值
max: (a: Int, b: Int) -> Int
min: (a: Int, b: Int) -> Int
max: (a: Float, b: Float) -> Float
min: (a: Float, b: Float) -> Float

// 幂运算
pow: (base: Float, exp: Float) -> Float
sqrt: (x: Float) -> Float

// 对数
log: (x: Float) -> Float
log2: (x: Float) -> Float
log10: (x: Float) -> Float

3.2 三角函数

yaoxiang

// 三角函数
sin: (x: Float) -> Float
cos: (x: Float) -> Float
tan: (x: Float) -> Float

// 反三角函数
asin: (x: Float) -> Float
acos: (x: Float) -> Float
atan: (x: Float) -> Float
atan2: (y: Float, x: Float) -> Float

3.3 常量

yaoxiang

// 数学常量
pi: Float = 3.141592653589793
e: Float = 2.718281828459045

第四章：字符串库

4.1 字符串操作

yaoxiang

// 字符串长度
length: (s: String) -> Int

// 字符串拼接
concat: (a: String, b: String) -> String

// 字符串分割
split: (s: String, delimiter: String) -> List(String)

// 字符串查找
find: (s: String, pattern: String) -> Option(Int)
contains: (s: String, pattern: String) -> Bool

// 字符串替换
replace: (s: String, old: String, new: String) -> String

// 字符串修剪
trim: (s: String) -> String
trim_left: (s: String) -> String
trim_right: (s: String) -> String

4.2 字符串转换

yaoxiang

// 类型转换
to_string: (x: Int) -> String
to_string: (x: Float) -> String
to_string: (x: Bool) -> String

// 解析
parse_int: (s: String) -> Result(Int, Error)
parse_float: (s: String) -> Result(Float, Error)

第五章：集合库

5.1 List 类型

yaoxiang

// List 类型
List: (T: Type) -> Type = {
    data: Array(T),
    length: Int,
    push: (T: Type) -> ((self: List(T), item: T) -> Void),
    pop: (T: Type) -> ((self: List(T)) -> Option(T)),
    get: (T: Type) -> ((self: List(T), index: Int) -> Option(T)),
    set: (T: Type) -> ((self: List(T), index: Int, value: T) -> Void),
    insert: (T: Type) -> ((self: List(T), index: Int, item: T) -> Void),
    remove: (T: Type) -> ((self: List(T), index: Int) -> Option(T)),
    clear: (T: Type) -> ((self: List(T)) -> Void),
    contains: (T: Type) -> ((self: List(T), item: T) -> Bool),
    sort: (T: Type) -> ((self: List(T)) -> List(T)),
    reverse: (T: Type) -> ((self: List(T)) -> List(T)),
    map: (T: Type, R: Type) -> ((self: List(T), f: (T) -> R) -> List(R)),
    filter: (T: Type) -> ((self: List(T), predicate: (T) -> Bool) -> List(T)),
    reduce: (T: Type, R: Type) -> ((self: List(T), initial: R, f: (R, T) -> R) -> R)
}

5.2 Map 类型

yaoxiang

// Map 类型
Map: (K: Type, V: Type) -> Type = {
    data: Array((K, V)),
    length: Int,
    insert: (K: Type, V: Type) -> ((self: Map(K, V), key: K, value: V) -> Void),
    get: (K: Type, V: Type) -> ((self: Map(K, V), key: K) -> Option(V)),
    remove: (K: Type, V: Type) -> ((self: Map(K, V), key: K) -> Option(V)),
    contains_key: (K: Type, V: Type) -> ((self: Map(K, V), key: K) -> Bool),
    keys: (K: Type, V: Type) -> ((self: Map(K, V)) -> List(K)),
    values: (K: Type, V: Type) -> ((self: Map(K, V)) -> List(V)),
    clear: (K: Type, V: Type) -> ((self: Map(K, V)) -> Void)
}

第六章：迭代器库

6.1 Iterator trait

yaoxiang

// Iterator trait
Iterator: (T: Type) -> Type = {
    Item: T,
    next: () -> Option(T),
    has_next: () -> Bool,
    map: (R: Type) -> ((f: (T) -> R) -> Iterator(R)),
    filter: (predicate: (T) -> Bool) -> Iterator(T),
    collect: () -> List(T),
    reduce: (R: Type) -> ((initial: R, f: (R, T) -> R) -> R),
    for_each: (f: (T) -> Void) -> Void
}

6.2 迭代器适配器

yaoxiang

// 范围迭代器（Range 是正式类型，运行时身份为三标量不可变记录，
// 不再借 Tuple 外壳；打印 `1..10` / `1..10..2`，结构相等，具名字段）
Range: Type = {
    start: Int,
    end: Int,
    step: Int,
    Iterator(Int)
}

// 使用（迭代器协议：std.range.iter/has_next/next，for 经静态类型派发）
for i in 0..10 {
    print(i)
}

// step 形态（双点，无新关键词）
for i in 0..10..2 {
    print(i)
}

Range(Int) 已正式落地——具名字段 r.start/r.end/r.step 可访问； x in r 运行时走 std.range.contains（界检查 + 步长对齐），证明管道识别为区间命题 x >= r.start && x < r.end && (x - r.start) % r.step == 0（区间保持区间，不物化）。 step=0 字面量编译期拒绝；动态 step=0 已 Result 化： std.range.iter → Result(Iterator, Error)、std.range.contains → Result(Bool, Error)，消费点用 ? 沿调用栈传播或 result.unwrap 显式分流；for/in 糖降级在 ir_gen 解包，Err 分支（动态 step=0）显式失败（abort_invalid_step），绝不静默死循环。接口实例化（类型体 Iterator(Int) 声明）的类型语法与静态分发已随 RFC-011a 阶段 1-2 落地：类型体应用项 Iterator(Int) 触发 Self ↦ Range 替换展开与完整性检查，通过后生成实现证明。动态分发已随阶段 3 落地：接口名未实例化即存在类型（List(Animal)），具体值进入存在类型位置自动包装为变体值，元素方法调用按实际类型分发（§6）。std.range 模块的运行时协议面暂仍由原生方法提供，迁移到接口分发为后续工作。

附录：标准库模块索引

模块	说明
`std.assert`	断言机制——运行时 assert + 编译期 Assert 精化类型
`std.option`	Option 类型
`std.result`	Result 类型
`std.collection`	List、Map 等集合类型
`std.string`	字符串操作
`std.array`	数组操作
`std.iterator`	迭代器（协议面当前由 `std.range` 提供）
`std.range`	Range 迭代器与区间谓词、适配器
`std.test`	测试断言库（值语义，RFC-036 §3）——首个纯 YaoXiang dogfooding 模块

A.2 IO 模块

模块	说明
`std.io`	标准输入输出
`std.file`	文件操作
`std.dir`	目录操作

A.3 数学模块

模块	说明
`std.math`	数学函数
`std.math.trig`	三角函数
`std.math.log`	对数函数

A.4 工具模块

模块	说明
`std.random`	随机数生成
`std.time`	时间日期
`std.assert`	编译期 `Assert(C)` 与运行时 `assert(x > 0)` 统一（RFC-030）
`std.regex`	正则表达式

标准库规范 ​

第一章：核心库 ​

1.1 基础类型 ​

1.2 Option 类型 ​

1.3 Result 类型 ​

1.4 错误传播 ​

1.5 断言（std.assert） ​

第二章：IO 库 ​

2.1 标准输入输出 ​

2.2 文件操作 ​

2.3 目录操作 ​

第三章：数学库 ​

3.1 基础数学函数 ​

3.2 三角函数 ​

3.3 常量 ​

第四章：字符串库 ​

4.1 字符串操作 ​

4.2 字符串转换 ​

第五章：集合库 ​

5.1 List 类型 ​

5.2 Map 类型 ​

第六章：迭代器库 ​

6.1 Iterator trait ​

6.2 迭代器适配器 ​

附录：标准库模块索引 ​

A.2 IO 模块 ​

A.3 数学模块 ​

A.4 工具模块 ​

标准库规范

第一章：核心库

1.1 基础类型

1.2 Option 类型

1.3 Result 类型

1.4 错误传播

1.5 断言（std.assert）

第二章：IO 库

2.1 标准输入输出

2.2 文件操作

2.3 目录操作

第三章：数学库

3.1 基础数学函数

3.2 三角函数

3.3 常量

第四章：字符串库

4.1 字符串操作

4.2 字符串转换

第五章：集合库

5.1 List 类型

5.2 Map 类型

第六章：迭代器库

6.1 Iterator trait

6.2 迭代器适配器

附录：标准库模块索引

A.2 IO 模块

A.3 数学模块

A.4 工具模块