# 玄铁泛型编程指南

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

---

### 泛型类

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

#### 基础示例：容器

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

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

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

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

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

#### 泛型参数命名

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

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

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

---

### 泛型函数

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

#### 基础示例：交换

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

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

#### 泛型函数与类型标注

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

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

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

---

### 支持的类型参数

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

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

### 可空修饰符 `?`

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

#### 语法规则

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

#### 与弱引用配合

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

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

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

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

#### 多层 `?` 的含义

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

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

---

### 当前局限

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

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

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

---

### 完整示例

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

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

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

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

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

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

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

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

---

*下一篇：[04_弱引用编程指南.md](./04_弱引用编程指南.md)*