Add images of json_documents: save() and load() (#5632)

* Add images of json_documents: save() and load() An image is a document stored so that loading it needs no parsing: save() writes the node index, the text and the decoded strings; the static load() reads an image written by save(). load() takes a pointer and size, a borrowed vector, or an owned rvalue vector; the nodes are copied so they are aligned and can be edited, while the text and decoded strings stay in the image. image_check controls how much load() trusts the input: full checks structure, bounds, strings and numbers, the parser's own guarantees; bounds checks structure and bounds only; none skips all checks, for images from a trusted source. Layout is little-endian only ("NJVI" header, nodes, text, decoded strings), following the idea of zero-copy formats such as FlatBuffers and YaFF; the check follows FlatBuffers' Verifier. New errors: parse_error.116 for a malformed image or a failed check, type_error.320 for a discarded document or a big-endian target. A dedicated fuzzer and 6,000 seeded corruptions, checked under ASan/UBSan, found and fixed two gaps: unchecked reserved header fields, and unbounded null/boolean offsets that could make dump() throw std::length_error. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix MSVC errors in image test and add image_check doc anchor Move the raw string literal out of the CHECK macro (MSVC preprocessor), cast 64-bit header fields to std::size_t (C4244 on 32-bit), and give the image_check section in load.md a real anchor for the mkdocs strict build. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Check each distinct string and float range once in the full image check The full check scanned the contents of every string node and every float token over its own range, so many nodes pointing to one large range made load() quadratic. The structural walk now only collects the ranges; after it, each kind is sorted and checked once per distinct range. Ranges of one kind that overlap without being identical are rejected, as save() never writes them (nodes that share a value share the whole range). The cost is linear in the size of the image plus sorting the ranges. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Adapt the image tests to named documents and last-wins lookups Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Test that the targets of links never reach an image Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Test lookups in loaded images with duplicate and colliding keys Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Release the list of large objects once load() has built the indexes Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Test that invalid UTF-8 of a loaded image is not copied into an editable document Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Document that editable documents refuse invalid UTF-8 copied from a loaded image Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Expect first-wins lookups in the image tests Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Avoid useless casts of header fields in the image tests Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix clang-tidy 22 findings in unit-json_view_image.cpp and image.hpp Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix MSVC C4244 and C2017 in the image test Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Fix the indentation of a loop in the image test Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Make json_view.hpp pass include-what-you-use ci_single_binaries runs IWYU with --error on every header. For json_view.hpp it suggested adding <array> (std::array is used), the headers that json.hpp already provides (abi_config, abi_macros, input_adapters, json_pointer, cpp_future, string_concat, value_t, json_fwd), and <version> for std::nullptr_t, and removing <cstddef>. - include <array> - keep <cstddef> (nullptr_t, size_t; IWYU attributes them to <version> and <cstring>) - tell IWYU not to suggest the headers that json.hpp provides: the amalgamated json_view.hpp only includes json.hpp, so including them here would duplicate their definitions - drop edit_storage.hpp, which edit.hpp includes Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Silence a clang-tidy C++17 finding in the image test bugprone-suspicious-stringview-data-usage flags data() of the source view under C++17, although the length is passed and checked by the REQUIRE before it. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Build the image link test without exceptions load_result() exists only with exceptions; with JSON_NOEXCEPTION the test loads the image with the check directly (a failed check aborts). Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Follow the renames from the review of the view builder The review of #5620 renamed document_data's tape/tape_size/tape_cap to nodes/node_count/node_capacity and made the decode arena a std::vector<char>; adapt the code of this change to it. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Rename the emit lambda in the image writer for Qt compatibility Qt defines emit as an empty macro, so a Qt header included before json_view.hpp broke the lambda's declaration (see #5865). The slots variables in the image tests are renamed as well. Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Address the review of json_document images Signed-off-by: Niels Lohmann <mail@nlohmann.me> * Regenerate the amalgamated headers Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-10-22 11:36:14 +00:00 · 2026-10-21 10:21:29 +02:00
1 parent 823eee3b59
commit 4971200b54
@@ -0,0 +1,104 @@
+# <small>nlohmann::basic_json_document::</small>save
+
+```cpp
+std::vector<std::uint8_t> save() const;
+```
+
+Writes the document as an *image*: a byte buffer that [`load`](load.md) reads back without parsing. The image holds
+the node index, the source text (plus, for an edited document, the number tokens edits wrote), and the decoded
+strings (plus the strings edits wrote) -- everything [`root()`](root.md) needs, with nothing left to parse.
+
+An edited document is written in its *current* state, with its values in document order, the way the library's own
+parser would have produced them for that JSON text: a member [`set`](set.md) added goes at the end, an
+[`erase`](erase.md)d member leaves no trace, and a float that is not finite (NaN or positive/negative infinity)
+becomes null, the same substitution [`dump()`](../basic_json_view/dump.md) makes. The same document always saves to
+the same bytes -- also across `BasicJsonType` and `#!cpp Editable`, since the image reflects document order and
+values only, not which specialization produced them.
+
+## Return value
+
+The image, as a `#!cpp std::vector<std::uint8_t>`. Pass it, or a pointer to its data together with its size, to
+[`load`](load.md) to read the document back.
+
+## Exception safety
+
+Strong guarantee: `save()` does not modify `#!cpp *this` (it is `#!cpp const`), so if it throws, the document is left
+exactly as it was, and the partially built image is discarded with the exception.
+
+## Exceptions
+
+Throws [`type_error.320`](../../home/exceptions.md#jsonexceptiontype_error320) if the document is
+[discarded](is_discarded.md) -- a default-constructed document, or one a failed [`parse()`](parse.md)/
+[`read()`](read.md) with `allow_exceptions == false` left discarded.
+
+On a big-endian target, throws `type_error.320` with a different message instead: the image format is little-endian
+only (see [Notes](#notes)).
+
+Throws [`out_of_range.416`](../../home/exceptions.md#jsonexceptionout_of_range416) if the node count, the text, or
+the decoded strings of the image would individually reach 4 GiB -- the same 32-bit offsets
+[`parse()`](parse.md#exceptions) and, for edits, [`set`](set.md)/[`push_back`](push_back.md) are already limited to.
+
+!!! failure "Example messages"
+
+    ```
+    [json.exception.type_error.320] cannot save a discarded json_document
+    ```
+    ```
+    [json.exception.type_error.320] json_document images need a little-endian target
+    ```
+    ```
+    [json.exception.out_of_range.416] images of 4 GiB or more are not supported by json_document
+    ```
+
+## Complexity
+
+Linear in the size of the document: the number of nodes, plus the length of the text and the decoded strings that end
+up in the image.
+
+## Notes
+
+**Format.** The image begins with a 64-byte header (the magic bytes `#!cpp "NJVI"`, a version number, the node count,
+and the sizes of the text and the decoded strings, all little-endian), followed by the nodes
+([16 bytes each](../../home/architecture.md#node-index-of-json-views)), the text and a `#!cpp '\0'`, and the decoded
+strings and a `#!cpp '\0'`. [`load`](load.md) checks the header, and the sizes it describes, before reading anything
+else -- see [`load`'s Exceptions](load.md#exceptions).
+
+!!! warning "Experimental"
+
+    The image format is versioned but not yet stable: it may change in an incompatible way before it is declared
+    stable. Use images to cache a document within one build of the library, or to hand one to another process running
+    the *same* build on the *same* (little-endian) machine -- not as a long-term storage format. Keep the original
+    JSON text if you need to read a saved document back with a future library version.
+
+**Little-endian only.** The image is written as raw little-endian bytes, with no byte-swapping. `save()` (and
+[`load`](load.md)) throw `type_error.320` on a big-endian target rather than silently produce bytes a big-endian
+reader could not interpret correctly.
+
+## Examples
+
+??? example "Caching a parsed document as an image"
+
+    The example below saves a parsed configuration as an image -- the way a service might cache one to answer later
+    requests without parsing the text again -- and confirms that loading it back gives exactly the same result as
+    parsing did, and that saving is deterministic.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__save.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__save.output"
+    ```
+
+## See also
+
+- [load](load.md) - read an image written by `save()`
+- [owns_source](owns_source.md) - return whether the document holds its own copy of the text
+- [`basic_json_view::dump`](../basic_json_view/dump.md) - serialize the document to JSON text instead of an image
+- [Images](../../features/json_view.md#images) - why and when to use images
+
+## Version history
+
+- Added in version 3.13.0.