第26.18章:JSON

English

1. 读取器,不是序列化器

fast_io.json 是 JSON 读取器。它提供流式 handler 接口、 建立在同一 parser 上的 DOM,以及无堆的固定 arena 形式。它不提供 JSON writer; 需要输出时用 print 写。

模块导出 fast_io::json 命名空间。parser 是单遍递归下降, 读一块缓冲区。字符串视图指向该缓冲区或解码 arena, 所以 source 必须比 document 活得久。

2. Parser 策略与限制

名字 含义
json_policy::none 拒绝带小数或指数的数字。不生成浮点转换代码。
json_policy::floating_point 接受实数。
default_json_policy floating_point。
max_depth 512;更深的文档会被拒绝。
max_nodes 节点/成员索引上限,低于 32 位索引空间。

策略是模板参数,不是运行期标志。内核或不支持 FPU 的目标可以实例化 json_policy::none,永远不会链接十进制转换器。

3. 流式 Handler

Handler 是 duck-typed 的。每个成员返回 void,并通过 throws 报告失败:

成员 调用时机
on_null()null。
on_bool(bool)true 或 false。
on_uint64(uint64)非负整数。
on_int64(int64)负整数。
on_float64(float64)实数。
on_string(u8string_view)解码后的字符串。
on_array_begin()数组开始。
on_array_end(n)有 n 个元素的数组结束。
on_object_begin()对象开始。
on_object_end(n)有 n 个成员的对象结束。
on_key(u8string_view)解码后的对象键。

因为每个回调都是 void,失败走 herbception,快路径不携带错误槽, 也没有逐回调分支。Handler 可以抛自己的错误来提前停止。

4. DOM

json::document 是 basic_document<native_global_allocator>。 它拥有两个扁平容器(values 和 members)以及一个解码 arena。树一遍建成,没有收尾步骤。


import fast_io.json;

int main()
{
    auto docs{::fast_io::json::parse(u8R"({"name":"fast_io","count":3})")};
    auto const &root{docs.root()};
    auto const *name{root.object_at(root, u8"name")};
}
成员 含义
root()根值。
operator[](i)带检查的值节点访问。
index_unchecked(i)已证明边界后的无检查访问。
first_child(v)数组的第一个子节点,或对象的第一个成员。
next_sibling(v)、next_member(m)遍历链。
array_at(arr, n)数组第 n 个元素,或 nullptr。
object_find(obj, key)按键找成员,或 nullptr。
object_at(obj, key)按键找值,或 nullptr。

value 暴露 kind、as_bool()、 as_uint64()、as_int64()、as_float64() 和 as_string()。访问器不做类型转换;先检查 kind。

5. 入口

入口 用途
parse<policy>(source) 返回 document;source 必须比它活得久。
parse_file<policy>(path) 映射文件并返回拥有映射和 document 的 loaded_document。
parse_into<policy>(source, handler) 流式写入调用者 handler;返回消费的字节数。
parse_into(source, handler, fixed_arena) constexpr/无堆形式,arena 由调用者拥有。
parse_callback(source, handler, cb) noexcept 回调形式;cb 收到错误句柄,成功时 domain == nullptr。
parse_async(source, handler) 流式 handler 上的协程 awaiter。
parse_document_async(source) 产出 document 的协程 awaiter。

parse_callback 把错误句柄所有权转给回调;不消费就调用 dispose_error。source 和 handler 必须比回调活得久, 不是反过来。

6. 错误与偏移

解析通过 herbception 通道报告三种错误: parse_errc::invalid(畸形)、parse_errc::end_of_file (截断)和 parse_errc::overflow(深度或节点限制)。 异常值不携带位置,所以保留的 json::parser 在失败后暴露 error_offset。


::fast_io::json::parser p{source, &arena};
try
{
    ::fast_io::json::parse_document(p, handler);
}
catch throws(::std::error e)
{
    println("failed at byte ", p.error_offset);
}

parse_callback 和异步 awaiter 遵循同一规则:回调收到错误句柄, 失败的 awaiter 从 await_resume() 重新抛出。

7. 生命周期规则

要点