第26.18章:JSON
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. 生命周期规则
- 字符串视图指向 source 缓冲区或解码 arena;source 必须比 document 活得久。
parse_file同时拥有映射和 document,所以销毁顺序正确。parse_into的 handler 必须比调用活得久,不是比返回的 document (没有 document)。- document 的节点索引是 32 位;解引用前检查
kind和链边界。 - source 消失后不要保留 document 的
u8string_view。
要点
fast_io.json是读取器,提供流式、DOM 和无堆形式。json_policy::none在编译期移除浮点支持。- Handler 是 duck-typed 的,通过 herbception 报告失败。
- DOM 是扁平的 two-container 树,有带检查和带检查的访问。
parse_file拥有映射;parse要求 source 比 document 活得久。- 错误是 invalid、end-of-file 或 overflow;
parser.error_offset给出字节位置。 - Parser 限制深度和节点数;它不提供 JSON writer。