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
- String views point into the source buffer or the decode arena; the source must outlive the document.
parse_fileowns the mapping and the document together, so their destruction order is correct.- A handler passed to
parse_intomust outlive the call, not the returned document (there is no document). - A document's node indices are 32-bit; check
kindand chain bounds before dereferencing. - Do not keep a
u8string_viewfrom a document after the source is gone.
Key Takeaways
fast_io.jsonis a reader with streaming, DOM and no-heap forms.json_policy::noneremoves floating-point support at compile time.- Handlers are duck-typed and report failure through herbceptions.
- The DOM is a flat two-container tree with checked and unchecked access.
parse_fileowns the mapping;parserequires the source to outlive the document.- Errors are invalid, end-of-file or overflow;
parser.error_offsetgives the byte position. - The parser bounds depth and node count; it does not provide a JSON writer.