std.csv是 Zerolang 标准库中面向 Agent 编程场景的 CSV 处理模块，提供不依赖堆分配的 CSV 校验、记录扫描、字段解码以及固定元数（fixed-arity）的写入函数。本文基于 std/csv.0 源码与 conformance/native/pass/std-csv.0 一致性测试，系统讲解其全部 9 个公开 API 的用法、RFC 4180 语义、错误行为与缓冲区规划方法，读完即可在 Zerolang 程序中安全地解析和生成 CSV 数据。

何时使用 std.csv

在 Zerolang 中，当程序需要对 CSV 输入做无分配的校验（validation）、记录扫描（record scanning）、字段解码（field decoding），或者需要生成字段数固定的小型 CSV 记录时，使用std.csv。

它适合的场景包括：

• 对一段完整载入内存的 CSV 字节做整体合法性判断；
• 按记录序号（ordinal）定位某一行、按字段序号（ordinal）取出某一列；
• 统计合法记录数、记录内字段数；
• 将若干字段编码成带转义的 CSV 文本写入调用方提供的缓冲区；
• 与std.fs、std.io等模块配合，把 CSV 解析作为纯字节处理环节嵌入更大的数据处理链路。

当前可用的 API

以下是std.csv当前可运行的全部公开接口（签名目录同时见于 skill-data/stdlib.md 中的std.csv一节）：

模块元数据标签

• effects：parse
• allocation behavior：不分配内存；解码出的字段与写入器输出均使用调用方存储（caller storage）
• target support：目标无关（target-neutral），不依赖宿主能力
• error behavior：Maybe助手在输入畸形或存储不足时返回 null
• ownership notes：记录切片从输入借用（borrow）；字段与写入器输出从调用方缓冲区借用
• examples：conformance/native/pass/std-csv.graph（对应可读源码 conformance/native/pass/std-csv.0）

快速上手：完整示例

原文档给出如下可运行示例，它演示了「整体校验 → 按序号取记录 → 按序号解码字段 → 与原字符串比对」的完整读路径：

pub fn main(world: World) -> Void raises { let input: Span<u8> = "name,quote\nAda,\"a,b\"\n" let record: Maybe<Span<u8>> = std.csv.record(input, 1_usize) var field_buf: [16]u8 = [0_u8; 16] var quote: Maybe<Span<u8>> = null if record.has { quote = std.csv.field(field_buf, record.value, 1_usize) } if std.csv.valid(input) && quote.has && std.mem.eql(quote.value, "a,b") { check world.out.write("csv ok\n") } }

几点需要留意的语言语义（均来自 docs/articles/language-reference.md 与 docs/articles/primitives.md）：

• Maybe<T>表示可选值：只有通过.has守卫（或在可失败上下文中处理）后，才能读取.value，这是图语义（graph semantics）而非格式约定；
• [16]u8是固定大小数组，Span<u8>是只读借用指针加长度，MutSpan<u8>是可写借用指针加长度；标准库助手普遍写入调用方自有存储，使分配行为保持可见；
• raises声明可失败函数，check显式传播失败，没有隐藏异常系统；
• std.mem.eql用于字节序列比较（见 std/mem.0）。

读路径源码解析：校验、计数与字段解码

std.csv的读路径以四个内部扫描助手为核心，全部实现在 std/csv.0 中。理解它们的扫描状态机，有助于判断边界行为。

记录终结符判定：csv_record_end

csv_record_end（std/csv.0）从给定起始位置扫描一条记录的结束位置，用in_quotes、after_quote、at_field_start三个状态跟踪引号上下文：

• 在引号内遇到"：若后一个字节也是"（""双写转义），则跳过两个字节，视为字面引号；否则闭合引号，进入after_quote；
• 在after_quote状态只接受,（继续下一字段）或\n（记录结束）；遇到\r时必须紧跟\n（CRLF），否则返回 null；出现其他字符直接返回 null——这保证了引号闭合后字段立即结束；
• 在非引号上下文，\n或 CRLF 标记记录结束；裸\r（不带\n）返回 null；
• 未闭合引号（扫描到末尾仍在in_quotes）返回 null。

csv_next_record_start（std/csv.0）在记录结束后按分隔符推进起始位置：CRLF 跳过 2 字节，LF 跳过 1 字节。

valid与recordCount

valid（std/csv.0）从偏移 0 开始循环：每轮调用csv_record_end定位记录结尾，再对记录切片调用csv_field_count校验字段结构；任何一步失败立即返回false，全部通过返回true。

recordCount（std/csv.0）逻辑与valid完全相同，只是累加合法记录条数，畸形输入返回 null。因此「valid为 true 时，recordCount必然返回非 null」这一结论由同一实现路径直接保证。

record：按序号借用记录切片

record（std/csv.0）同样逐条扫描，当count == ordinal时返回bytes[start..end.value]——注意返回的切片不包含行终止符（CRLF 或 LF），便于后续直接传给fieldCount/field。序号越界或输入畸形时返回 null。

fieldCount与field：字段计数与解码

fieldCount（std/csv.0）对一条记录计数，初始为 1，遇到未被引用的,加一；未闭合引号、字段中裸引号、字段中含 LF/CR 都返回 null。

field（std/csv.0）是读路径最复杂的函数：它把目标字段解码进调用方缓冲区（MutSpan<u8>），并处理""双写转义的还原（把连续两个引号写为单个"）。它返回buffer[..output]，即只包含实际写入字节数的切片。返回 null 的情形包括：

• 字段序号越界（ordinal >= fields.value）；
• 缓冲区不足以容纳解码结果（output >= std.mem.len(buffer)）；
• 引号未闭合、引号后紧跟非法字符、非引号字段中出现引号/LF/CR 等畸形结构。

这一设计意味着缓冲区大小必须覆盖解码后的字段字节数（""还原为"后字节数会减少），而非原始记录片段长度。

写路径源码解析：字段与记录的编码

encodedFieldLen：编码长度预算

csv_field_needs_quotes（std/csv.0）判定字段是否需要加引号：空字段不加引号；字段内含,、"、\n、\r中的任意一个即需加引号。

encodedFieldLen（std/csv.0）据此计算写入后占用的字节数：无需加引号时等于std.mem.len(field)；需要加引号时为2 + len + 字段内引号个数（首尾各 1 个引号，每个内部引号双写多占 1 字节）。

例如测试 conformance/native/pass/std-csv.0 验证的取值：

• std.csv.encodedFieldLen("plain") == 5（无引号字段原样写入）；
• std.csv.encodedFieldLen("a,b") == 5（即"a,b"共 5 字节）；
• std.csv.encodedFieldLen("a\"b") == 6（即"a""b"共 6 字节）。

writeField：单字段写入

writeField（std/csv.0）先按encodedFieldLen检查缓冲区容量，不足则返回 null；无需引号时原样拷贝，需要引号时写入首引号、逐字节拷贝并在每个内部引号处重复一次、写入尾引号。

writeRecord2/writeRecord3：定长记录写入

两个记录写入器是固定元数（fixed-arity）封装：

• writeRecord2（std/csv.0）：先预算left_len + 1 + right_len + 1字节（两个字段间一个,，末尾一个\n），随后依次写入左字段、逗号、右字段、换行；
• writeRecord3（std/csv.0）：同理，预算first_len + 1 + second_len + 1 + third_len + 1。

两者的容量检查都发生在写入之前：只要任一字段经过编码后总长超出缓冲区，就直接返回 null，不会产生半截写入。测试中的两个输出示例：

std.csv.writeRecord2(buf, "Ada", "a,b") // "Ada,\"a,b\"\n" std.csv.writeRecord3(buf, "x", "y\"z", "") // "x,\"y\"\"z\",\n"

注意三字段示例中，空字段""被原样写成空（encodedFieldLen对空字段返回 0，不加引号），因此输出以,紧邻\n结尾。

错误行为与内存模型

原文档定义了四条元数据约束，本文结合源码进一步展开：

1. 无分配：std.csv全部助手只接受Span<u8>（只读输入）与MutSpan<u8>（调用方可写缓冲区），全程无堆分配。解码字段写入调用方数组，记录切片是输入字节的借用视图。这一点与 Zerolang 的整体内存模型一致：标准库助手普遍写入调用方自有存储，让分配行为保持可见（见 docs/articles/primitives.md）。
2. 目标无关：std.csv不依赖进程参数、文件系统或网络等宿主能力，属于 target-neutral 助手，与std.args、std.fs、std.http等 hosted 能力模块（见 docs/articles/standard-library.md）形成对比，可安全用于 freestanding / edge 类目标。
3. Maybe错误传递：所有可能失败的读/写助手都以Maybe<T>返回 null 表示「畸形输入」或「存储不足」，而不是抛出异常。调用方应始终检查.has，正如 skill-data/stdlib.md 所强调的：优先做Maybe<T>返回检查，而不是假设操作成功。
4. 所有权：record返回的切片借用输入bytes，其生命周期受输入约束；field/writeField/writeRecord2/writeRecord3返回的切片借用调用方缓冲区。没有隐藏的运行时清理注册表，所有权的显式性可通过图检查（graph inspection）直接观察。

边界行为与缓冲区规划

畸形输入与边界案例

一致性测试 conformance/native/pass/std-csv.0 覆盖了大量边界，可作为行为契约：

缓冲区容量估算

写路径的容量预算是确定性可算的，推荐先用encodedFieldLen做预算再分配数组：

var buf: [24]u8 = [0_u8; 24] let rec: Maybe<Span<u8>> = std.csv.writeRecord2(buf, "Ada", "a,b")

• 两字段记录所需容量 =encodedFieldLen(left) + 1 + encodedFieldLen(right) + 1；
• 三字段记录所需容量 =encodedFieldLen(first) + 1 + encodedFieldLen(second) + 1 + encodedFieldLen(third) + 1；
• 解码一个字段所需的缓冲区至少为解码后的字节数（""还原后变小，因此按原始字段长度准备通常足够）。

测试同样验证了容量不足时返回 null：writeField用 3 字节缓冲写"a,b"（需要 5 字节）、writeRecord2用 8 字节缓冲写Ada,"a,b"（需要 12 字节）都返回 null。

设计要点小结

• CSV 助手遵循 RFC 4180 常见字段规则：逗号分隔字段、引号字段、引号字段内双写引号转义、CRLF 或 LF 记录分隔符；引号字段可包含换行。
• 写入器表面是固定元数的：writeRecord2/writeRecord3只覆盖 2 / 3 字段记录；当需要自定义写入循环（如不定字段数、追加到已存在记录等）时，应改用writeField自行逐字段写入并拼接分隔符与换行。
• 由于模块目标无关、零分配且错误显式化，std.csv非常适合嵌入 Agent 生成的数据处理代码：Agent 可通过图事实（graph facts）与zero query等工具直接核查函数签名与所有权关系，而运行时行为则由std.csv.valid+Maybe检查构成确定性的输入契约。