Add editable json_documents: set, push_back, insert, and erase

[nlohmann]

Adds editable documents to the view: set, push_back, insert and erase on a new Editable variant of basic_json_document; part of the zero-copy view stack for #5295, on top of #5628.

Summary

basic_json_document and basic_json_view get a second template parameter, Editable (false by default). The new aliases json_editable_document, json_editable_view, ordered_json_editable_document and ordered_json_editable_view can change the document they hold:

• set(view, value) replaces a value;
• set(object, key, value) assigns a member or adds it, and a null becomes an object. With duplicate keys, the first member is assigned and the others are removed;
• set(array, index, value) assigns an element;
• set(json_pointer, value) sets the member or element that a pointer names. "-" or the size of the array appends. Below a null parent, a last token of "-" or digits creates an array (padded with nulls up to the index), as basic_json::operator[] does; any other token creates an object;
• push_back(array, value) appends, and a null becomes an array;
• insert(array, index, value) inserts before an element (index <= size()) and returns a view of the new element;
• erase(object, key) removes all members with the key and returns their number;
• erase(array, index) removes an element;
• erase(json_pointer) removes the member or element a pointer names and returns the number of removed values.

A value can be a view (of any document; it is copied), a BasicJsonType value, or anything BasicJsonType can be constructed from. A view of an erased value keeps its last value; views of other values keep referring to them when elements move. Views of editable and read-only documents compare with each other.

How edits are stored

• The source text is never written.
• The parsed index never moves. New values and element sequences go to storage that the document owns and that never moves (detail/view/edit_storage.hpp). So views stay valid, and a view keeps referring to its value: after an assignment, it sees the new value.
• An array or object whose elements change gets its elements in a separate sequence. Entries of that sequence link to the values, which stay where they are. Iterators taken over such a container before its first edit are invalidated.
• Replacing a container by a scalar does not walk from the root once the parent is linked (linked flag), so loops of set(view, ...) are linear.
• Copying a nested value into the document is iterative, so a deeply nested value cannot overflow the stack. set encodes the new value into the document's storage before it touches anything reachable from the root; assign() does not leave a half-assigned container if set_moved() throws.
• The edit arena can grow to 4 GiB - 1 bytes.
• Views of read-only documents walk the plain node array through detail::view::navigation<false> and compile without any of this. That policy does not change behavior.

Errors

• They are those of basic_json where the operation corresponds: type_error.305/307/308/309, out_of_range.401/403/405, parse_error.106/109.
• A view of another document is invalid_iterator.202.
• Strings and keys are checked for UTF-8 when they enter the document, including those copied from another document, with the same type_error.316 message as basic_json::dump() for the same string. So an editable document only ever holds valid UTF-8, and dump() never throws.
• Binary values cannot be stored: this is the new type_error.319 (listed in exceptions.md, with insert among the functions that throw it).
• Edits of 4 GiB or more end with out_of_range.416, as documents of that size do.

Docs and other touched areas

New pages for set, push_back, insert, erase and the four aliases; an "Editing a document" section in the view article; the architecture page describes the edited layout; the banner of json_view.hpp mentions editable documents; .github/labeler.yml and BUILD.bazel list the new files. The lookup, iterator, serializer and number code in detail/view/ is templated on Editable.

Performance

Read-only documents are within about 1% of the previous PR for parse, traversal and dump(): the plain paths do not carry the edit bookkeeping.

The core library (json::parse / dump) is not affected: this PR only adds code to the view.

Tests

unit-json_view_edit.cpp holds a seeded differential test that applies random assignments, member and element changes, inserts, erases (directly and through JSON pointers), copies within and between documents, and pushes, both to an ordered_json_editable_document and to the equivalent ordered_json value, and compares serialized, materialized, compared and read-back results after every edit.

Further tests cover:

• the errors; views and strings that stay valid while the edit arena grows; the size of a text arena;
• numbers (NaN, infinities, extremes, number_format::source);
• nulls that become containers, a replaced root, and JSON pointers below null values;
• deeply nested values from read-only views, editable views, edited documents and basic_json values;
• strings of other documents being checked for UTF-8;
• replacing arrays and objects by scalars;
• duplicate keys (parsed layout, moved layout, large objects with an index, objects in moved arrays and in new values, values of other documents);
• documents reused with read().

Public API

No breaking changes. The view API is new in this stack, so nothing here changes a released interface.

• basic_json_document and basic_json_view get a defaulted template parameter. Code that names them with one argument, or uses the existing aliases, is unaffected.
• New aliases json_editable_document, json_editable_view, ordered_json_editable_document, ordered_json_editable_view; set, push_back, insert and erase exist only on editable documents (calling them on a read-only document is a static_assert).
• New exception id type_error.319 (binary values cannot be stored). The basic_json error ids listed above are also thrown by the view's edits; out_of_range.416 now also covers edits of 4 GiB or more.
• Decisions: set(object, key, ...) with duplicate keys assigns the first member and removes the others, so lookups, iteration and materialize() agree; iterators over a container become invalid when its elements are first edited.

---

Written by Claude Code.

🤖 Generated with Claude Code

[nlohmann]

CI fixes for this PR (commit f72fe8d, plus the lower fixes merged in). CI had not run yet; these were found locally with gcc:16 (linux/amd64) and the CI flags:

• ci_test_gcc: in unit-json_view_edit.cpp, std::mt19937::result_type is std::uint_fast32_t (unsigned long on Linux), so returning it as std::uint32_t failed -Werror=conversion. It is now converted explicitly through a named variable. static_cast<std::uint64_t>(18446744073709551615u) and static_cast<std::int64_t>(-9223372036854775807 - 1) were useless casts there and are now std::numeric_limits<...>::max()/min().
• ci_test_noexceptions: exception_of_call() catches outside a CHECK_THROWS, so the invalid-UTF-8 checks aborted with JSON_NOEXCEPTION. They are now compiled only with exceptions.

Verified: unit-json_view_edit builds and passes (C++11/C++20 with the CI flags, and a JSON_NOEXCEPTION build run as --no-throw). #5631 got only a propagation merge.

— posted by Claude Code on behalf of @nlohmann

[github-actions]

🔴 Amalgamation check failed! 🔴

The source code has not been amalgamated and/or formatted correctly, or BUILD.bazel is out of date.