# 标准库与 Runtime API

玄铁在底层 Runtime (`xt_runtime.c`) 提供了丰富的内置函数和标准库对象方法，这些 API 可以直接在语言层被调用：

## 全局内置原语
*   **基础交互**：[`示(内容)`](../关键字/示.md) (等同于 Print)
*   **数据转换**：[`化(对象)`](../关键字/化.md) (JSON序列化)，[`解(字符串)`](../关键字/解.md) (JSON反序列化)
*   **系统与网络**：
    *   [`执(命令)`](../关键字/执.md)：执行系统命令 (Execute)
    *   [`输(提示)`](../关键字/输.md)：读取标准输入 (Input)
    *   [`听(端口, 处理函, 绑定地址?)`](../关键字/听.md)：网络监听 (Listen)；缺省只绑回环 `127.0.0.1`，对外监听须显式传 `"0.0.0.0"`
    *   [`求(地址)`](../关键字/求.md)：发起 HTTP 请求 (Request)，支持 https（TLS 走系统原生通道：Windows=Schannel / macOS=SecureTransport；Linux 暂无）；单参 GET 自动跟随 301/302/303/307/308 重定向（≤5 跳）、默认 Chrome User-Agent、连接 10s/收发 30s 超时；详见 [08_网络与并发编程指南](../08_网络与并发编程指南.md)
    *   [`连(地址)`](../关键字/连.md)：建立网络连接 (Connect)

## URL 编解码与字节转换

| 函数 | 返回 | 行为 |
|------|------|------|
| `URL编码(串)` | `字` | 按 RFC 3986 做百分号编码：`A-Z a-z 0-9 - _ . ~` 直通，其余按 UTF-8 字节转 `%XX`（大写）；空格 → `%20`；空串 → 空串。**URL 里带中文/空格/特殊字符时必须先编码**——`求` 不做编码，未编码的中文会得到"成功但空体"（服务端拒答，容易误判） |
| `URL解码(串)` | `字` | `%XX`（十六进制大小写均可）→ 原字节；`+` **原样保留**（RFC 3986，不做 form 的空格还原）。转义不完整 / 非十六进制 / 结果非合法 UTF-8 一律**明确报错退出**（提示含偏移） |
| `字节到字符串(字节)` | `字` | 字节流按 UTF-8 严格校验后还原为字符串；非法字节或非字节输入**明确报错退出**。取字节流可用 `字节(容量)` 建缓冲、`.追加(字节值)` 逐个写入 |

```xuantie
设 地址 = "https://example.com/search?q=" & URL编码("玄铁 语言")
示(URL解码("%E7%8E%84%E9%93%81"))     // 玄铁
```

## 类型转换（整/小数/字）
把值显式转换为另一类型。`整()`/`小数()` 返回**结果**容器（失败不炸，可判定）;`字()` 直接返回字符串。

| 函数 | 返回 | 行为 |
|------|------|------|
| [`整(x)`](../关键字/整.md) | `结果<整>` | 整数原样；`真/假`→`1/0`；小数→**截断取整**(`整(3.7)=3`)；字符串→严格解析(`整("42")=42`),非数字串失败；`空` 失败 |
| [`小数(x)`](../关键字/小数.md) | `结果<小数>` | 整数→小数(`小数(5)=5.0`)；数字符串解析(`小数("3.14")=3.14`)；失败同 整 |
| [`字(x)`](../关键字/字.md) | `字`（直接） | 任意值转文本：`字(42)="42"`、`字(3.7)="3.7"`、`字(真)="真"`、数组→`"数组对象"` 这类占位描述 |

**结果容器判定写法**（失败不会中断程序）：

```xuantie
设 转 = 整(输("请输入数字:"))
若 转.成功 {
    示("两倍 = " & 字(转.值 * 2))
} 否 {
    示("不是数字: " & 转.错误)
}
```

**注意**:`整("12abc")`、`整("")`、`整("1.5")`（带小数点的串）都判失败——字符串必须是**纯整数文本**。要解析小数请用 `小数()`。

*   **JSON 转换**：`化(对象)` (序列化为 JSON 文本)，`解(字符串)` (解析 JSON 文本为字典/数组)

## 标准库命名空间
*   **文件 ([`文件`](../关键字/文件.md).)**：
    *   [`文件.读(路径)`](../关键字/文件.md)：返回 `结果` 容器——成功时 `.值` 为文件内容字符串，失败时 `.错误` 为原因
    *   [`文件.写(路径, 内容)`](../关键字/文件.md)：返回 `结果` 容器——成功时 `.值` 为 `真`，失败时 `.错误` 为原因
    *   [`文件.存在?(路径)`](../关键字/文件.md)：返回布尔
    *   用法：`设 r = 文件.读(路径) ; 若 r.成功 { 设 内容 = r.值 }`——不要把 `文件.读` 的返回值直接当字符串用
*   **数学 ([`数学`](../关键字/数学.md).)**：
    *   [`数学.随机(上限)`](../关键字/数学.md): 0..上限-1 的随机整数；[`数学.平方根`](../关键字/数学.md)/幂/绝对值/正弦/余弦/最大值/最小值/取整/进一/四舍五入 详见详情页；常量 [`数学.圆周率`](../关键字/数学.md) 与 [`数学.自然常数`](../关键字/数学.md)(裸写或加括号均可)
*   **时间 ([`时`](../关键字/时.md).)**：
    *   [`时.现()`](../关键字/时.md): 当前 Unix 时间戳（秒）
    *   [`时.毫秒()`](../关键字/时.md), [`时.微秒()`](../关键字/时.md): 高精度单调计时（测耗时用）
    *   [`时.睡(毫秒)`](../关键字/时.md): 休眠（在 异步 块内是 fiber 切分点，详见详情页）

## 数组

> 详情页：[数组](../关键字/数组.md) ｜ 完整教程：[06 数组编程指南](../06_数组编程指南.md)

数组支持动态扩容、索引访问和丰富内置方法。创建：`设 列表 = [1, 2, 3]`；索引：`列表[0]`；长度：`列表.长度`。

**内置方法**：`追加`(append)、`删`(remove)、`插`(insert)、`找`(find)、`含?`(contains)、`连接`(join)。

**高阶方法**（通过 `引 "../lib/数组.xt" 予 A` 引入标准库）：`A.映射`(map)、`A.过滤`(filter)、`A.归纳`(reduce)、`A.查找`(find)、`A.每个?`(every)、`A.存在?`(some)、`A.排序`(sort)、`A.去重`(dedup)、`A.反转`(reverse)。

> 完整教程、详细示例与输出请参阅：[06_数组编程指南.md](../06_数组编程指南.md)

## 字符串方法

> 详情页：[字符串](../关键字/字符串.md)

*   常用成员：`截取` (substring)、`包含?`/`含?` (contains)、`替换` (replace)、`分割` (split)、`字符数`/`长度`(字节数) 等属性读取；**拼接用 `&` 运算符**（没有 `拼接` 方法，实测调用会报对象不存在的方法）。
*   `分割` 语义（同 Python `split`）：分隔符按**完整字面子串**匹配，**保留空段**。例：`"a,b,,c".分割(",")` → `["a","b","","c"]`（4 段）；`"a,b,,c".分割(",,")` → `["a,b","c"]`（2 段）；`"".分割(",")` → `[""]`。分隔符为空串 `""` 时按逻辑字符逐字拆分：`"你好".分割("")` → `["你","好"]`。

## 字典方法

> 详情页：[字典](../关键字/字典.md)

*   支持 `设置` (set)、`获取` (get)、`包含?` (contains)、`键集` (keys) 等。

## 字典字面量的键写法

键支持三种写法（同一字典可混用）：

```xuantie
设 配置 = {"名称": "玄铁", 版本: 1, ("动态" & 后缀): 真}
```

*   **引号字符串键**：`{"名称": "玄铁"}` —— 经典写法，任何内容都可作键。
*   **裸标识符键**（CSS 风）：`{版本: 1}` —— 标识符紧跟冒号时直接作字符串键，不当变量求值。UI 库选项推荐此写法：`{宽: 240, 圆角: 8, 点击: 函() {...}}`。
*   **括号表达式键**：`{(变量): 值}` —— 要用变量/表达式的值作键时**必须加括号**（否则会被当裸键字面量）。

注意：**关键字作键仍需引号**（如 `{"选": 1}`，因 `选` 是通道关键字）；裸键仅限标识符。