玄铁泛型编程指南

泛型允许你编写可复用的代码，操作不同类型的数据而无需为每种类型重复实现。玄铁的泛型语法简洁直观，与类型系统深度整合。

---

泛型类

使用 型 定义类时，在类名后添加 <T> 来声明泛型参数。类内部可以像使用普通类型一样使用 T。

基础示例：容器

// 定义一个泛型容器类
型 盒子<T> {
    设 内容: T

    函 造(初始内容: T) {
        此.内容 = 初始内容
    }

    函 获取(): T {
        返 此.内容
    }
}

// 实例化整数盒子
设 整盒 = 造 盒子<整>(123)
示("整盒内容: #{整盒.获取()}")  // 输出: 整盒内容: 123

// 实例化字符串盒子
设 字盒 = 造 盒子<字>("玄铁")
示("字盒内容: #{字盒.获取()}")  // 输出: 字盒内容: 玄铁

泛型参数命名

泛型参数使用尖括号 < > 包裹，多个参数用逗号分隔：

型 键值对<K, V> {
    设 键: K
    设 值: V

    函 造(k: K, v: V) {
        此.键 = k
        此.值 = v
    }
}

---

泛型函数

在 函 关键字后的函数名后添加 <T> 来定义泛型函数。调用时在函数名后添加 <具体类型>。

基础示例：交换

函 交换<T>(a: T, b: T) {
    返 [b, a]
}

设 换后 = 交换<整>(10, 20)
示("交换结果: #{换后}")  // 输出: 交换结果: [20, 10]

泛型函数与类型标注

泛型函数支持完整的类型注解：

函 恒等<T>(x: T): T {
    返 x
}

示(恒等<字>("你好"))  // 输出: 你好
示(恒等<整>(42))     // 输出: 42

---

支持的类型参数

实例化泛型时，可以使用以下类型作为类型参数：

类型	关键字	示例
整数	整	盒子<整>
字符串	字	盒子<字>
浮点数	小数	盒子<小数>
布尔	布尔	盒子<判>
数组	数组	盒子<数组>
字典	字典	盒子<字典>
结果	结果	盒子<结果>
字节	字节	盒子<字节>
自定义标识符	T, U 等	交换<T>

可空修饰符 ?

在泛型类型参数中，? 可以紧跟在类型后面，表示该类型可空。? 修饰的是它紧邻的那个类型——这个规则清晰且与主流语言一致。

语法规则

节点?              ← 节点 可空
数组<节点>?        ← 数组 可空（整个数组可能为空）
数组<节点?>        ← 数组里的元素可空（数组本身存在）
数组<节点?>?       ← 数组可空，且元素也可空
字典<字, 节点?>    ← 字典里 value 可空
字典<字, 节点>?    ← 整个字典可空

与弱引用配合

弱 修饰的字段必须是可空类型——因为它引用的对象随时可能被释放而变空：

型 子节点 {
    弱 设 父: 父节点?    // 弱引用父节点，父可能被释放→变为空
}

型 父节点 {
    设 子: 数组<子节点>  // 强引用子节点列表
}

这里 父: 父节点? 中的 ? 明确表达了"父可能为空"的语义，而 弱 保证了不会形成循环引用。

多层 ? 的含义

数组<节点?>?     ← 解读：外层的 ? 修饰数组，里层的 ? 修饰节点
                // 数组本身可空（可能为 空）
                // 数组元素也可空（某个元素可能是 空）

字典<字, 整?>    ← 字典的键不可空，值可空

---

当前局限

注意：v0.18.0 版本中，泛型支持处于语法层。编译器采用类型擦除策略，所有泛型类型在底层均映射为 i64。这意味着：

• 泛型参数的类型检查在编译期尚未强制执行
• 泛型约束（<T 承 接口>）尚未实现
• 泛型类型的运行时反射信息有限

这些功能将在后续版本中逐步完善。

---

完整示例

// 测试完整的泛型功能
示("--- 泛型示例 ---")

// 泛型类
型 栈<T> {
    设 数据

    函 造() {
        此.数据 = []
    }

    函 压入(元素: T) {
        此.数据.追加(元素)
    }

    函 弹出(): T {
        设 顶值 = 此.数据[此.数据.长度 - 1]
        此.数据.删(此.数据.长度 - 1)
        返 顶值
    }
}

// 使用整数栈
设 整栈 = 造 栈<整>()
整栈.压入(10)
整栈.压入(20)
示("弹出: #{整栈.弹出()}")  // 20

// 泛型函数：最大值
函 取较大<T>(a: T, b: T): T {
    若 a > b { 返 a }
    返 b
}

示("较大值: #{取较大<整>(10, 20)}")  // 20

---

下一篇：04_弱引用编程指南.md