Ch26.18: JSON

中文(简体)

1. A Reader, Not a Serializer

fast_io.json is a JSON reader. It provides a streaming handler interface, a DOM built over the same parser, and a no-heap fixed-arena flavour. It does not provide a JSON writer; write the output with print if you need one.

The module exports the namespace fast_io::json. The parser is a single-pass recursive descent over one buffer. String views point into that buffer or into the decode arena, so the source must outlive the document.

2. Parser Policy and Limits

Name Meaning
json_policy::none Reject numbers with a fraction or exponent. No floating-point conversion is emitted.
json_policy::floating_point Accept real numbers.
default_json_policy floating_point.
max_depth 512; deeper documents are rejected.
max_nodes Node/member index ceiling, below the 32-bit index space.

The policy is a template parameter, not a runtime flag. A kernel or a no-FPU target can instantiate json_policy::none and never link a decimal converter.

3. The Streaming Handler

A handler is duck-typed. Every member returns void and reports failure through throws:

Member Called for
on_null()null.
on_bool(bool)true or false.
on_uint64(uint64)Non-negative integer.
on_int64(int64)Negative integer.
on_float64(float64)Real number.
on_string(u8string_view)Decoded string.
on_array_begin()Start of an array.
on_array_end(n)End of an array with n elements.
on_object_begin()Start of an object.
on_object_end(n)End of an object with n members.
on_key(u8string_view)Decoded object key.

Because every callback is void and failures are herbceptions, the fast path carries no error slot and no per-callback branch. The handler can stop early by throwing its own error.

4. The DOM

json::document is basic_document<native_global_allocator>. It owns two flat containers (values and members) and a decode arena. The tree is built in one pass; there is no finalisation step.


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")};
}
Member Meaning
root()The root value.
operator[](i)Checked access to a value node.
index_unchecked(i)Unchecked access after a proven bound.
first_child(v)First child of an array or first member of an object.
next_sibling(v), next_member(m)Walk the chain.
array_at(arr, n)Nth element of an array, or nullptr.
object_find(obj, key)Member by key, or nullptr.
object_at(obj, key)Value by key, or nullptr.

value exposes kind, as_bool(), as_uint64(), as_int64(), as_float64() and as_string(). The accessor does not convert between kinds; check kind first.

5. Entry Points

Entry Use
parse<policy>(source) Return a document; the source must outlive it.
parse_file<policy>(path) Map a file and return a loaded_document that owns the mapping and the document.
parse_into<policy>(source, handler) Stream into a caller handler; returns bytes consumed.
parse_into(source, handler, fixed_arena) Constexpr/no-heap form with a caller-owned arena.
parse_callback(source, handler, cb) Noexcept callback form; cb gets the error handle, success has domain == nullptr.
parse_async(source, handler) Coroutine awaiter over the streaming handler.
parse_document_async(source) Coroutine awaiter that yields a document.

parse_callback transfers ownership of the error handle to the callback; call dispose_error if you do not consume it. The source and handler must outlive the callback, not the other way around.

6. Errors and Offsets

Parsing reports three error kinds through the herbception channel: parse_errc::invalid (malformed), parse_errc::end_of_file (truncated) and parse_errc::overflow (depth or node limit). The exception value does not carry a position, so a retained json::parser exposes error_offset after the failure.


::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 and the async awaiter follow the same rule: the callback receives the error handle, and a failed awaiter rethrows from await_resume().

7. Lifetime Rules

Key Takeaways