Document insert() and erase() of editable json_documents

Add API reference pages for basic_json_document::insert and
basic_json_document::erase, matching the style of set.md and
push_back.md: signatures, parameters, return values, exception safety,
exceptions with their exact ids and messages, complexity, notes on
duplicate keys and view/iterator validity, and an example.

Add example programs basic_json_document__insert.cpp and
basic_json_document__erase.cpp with their expected output, each
comparing an edit on an editable document with the same edit on a
plain json value to show what is preserved: member order, the
spelling of untouched numbers, and, for insert, that a view taken
before the insert keeps referring to the same element after its index
shifts.

Register both new pages in mkdocs.yml, docSet.sql, and the member list
of basic_json_document/index.md, add cross-references to them from
set.md and push_back.md, and mention insert/erase in the "Editing a
document" section of features/json_view.md.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/docset/docSet.sql

@@ -131,6 +131,8 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json::~basic_json', 'Me
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document', 'Class', 'api/basic_json_document/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::basic_json_document', 'Constructor', 'api/basic_json_document/basic_json_document/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::accept', 'Function', 'api/basic_json_document/accept/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::erase', 'Method', 'api/basic_json_document/erase/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::insert', 'Method', 'api/basic_json_document/insert/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::is_discarded', 'Method', 'api/basic_json_document/is_discarded/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::memory_usage', 'Method', 'api/basic_json_document/memory_usage/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_document::node_count', 'Method', 'api/basic_json_document/node_count/index.html');

docs/mkdocs/docs/api/basic_json_document/erase.md

@@ -0,0 +1,128 @@
+# <small>nlohmann::basic_json_document::</small>erase
+
+```cpp
+// (1)
+std::size_t erase(view_type object, string_view_t key);
+
+// (2)
+template<typename I>
+void erase(view_type array, I idx);
+
+// (3)
+std::size_t erase(const json_pointer& ptr);
+```
+
+Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+has `erase`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
+
+1. Removes every member of `object` whose key is `key` (see [Notes](#notes) on duplicate keys) and returns how many
+   were removed; `#!cpp 0` if `object` has no member with this key.
+2. Removes the element at index `idx` of `array`, which must already exist (`#!cpp idx < array.size()`).
+3. Removes the value the JSON pointer `ptr` refers to, relative to [`root()`](root.md), and returns how many values
+   were removed: the *parent* of the target must already exist, and the target itself is removed as in 1. (an object
+   member; `#!cpp 0` or more) or 2. (an array element; always `#!cpp 1`). `ptr` must not be empty -- [`root()`](root.md)
+   itself cannot be erased.
+
+## Template parameters
+
+`I`
+:   an integral type other than `#!cpp bool`, deduced (overloads taking a `#!cpp bool` or a non-integral type for
+    `idx` do not participate in overload resolution).
+
+## Parameters
+
+`object` (in)
+:   the object to remove a member of
+
+`array` (in)
+:   the array to remove an element of
+
+`key` (in)
+:   the key of the member(s) to remove
+
+`idx` (in)
+:   the index of the element to remove; a negative value throws (see [Exceptions](#exceptions))
+
+`ptr` (in)
+:   a JSON pointer to the value to remove, relative to `root()`
+
+## Return value
+
+1. the number of removed members (`#!cpp 0` if `object` had none with this `key`)
+2. (nothing)
+3. the number of removed values (`#!cpp 0` or more for an object member, always `#!cpp 1` for an array element)
+
+## Exceptions
+
+1. Throws [`type_error.307`](../../home/exceptions.md#jsonexceptiontype_error307) if `object` is not an object -- the
+   same message [`BasicJsonType::erase`](../basic_json/erase.md) throws for the same type.
+2. Throws `type_error.307` if `array` is not an array. Throws
+   [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if `idx` is negative, or if
+   `#!cpp idx >= array.size()`.
+3. Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) ("JSON pointer has no parent")
+   if `ptr` is empty. Throws what [`at`](../basic_json_view/at.md) throws (overload 3) for resolving `ptr`'s parent.
+   For the last reference token itself: if the parent is an array, throws what 2. throws for an index that is out of
+   range, or, for a token that is not a valid array index,
+   [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) (a leading `#!cpp '0'`),
+   [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) (not a number),
+   [`out_of_range.410`](../../home/exceptions.md#jsonexceptionout_of_range410) (too large for `size_type`), or
+   [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) (an empty token); otherwise (an
+   object, or a primitive value the pointer's parent resolves to) throws what 1. throws.
+
+Every overload also throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) ("view
+does not belong to this document") if `object`/`array` is a [discarded](../basic_json_view/is_discarded.md) view or a
+view of a *different* document (overloads 1-2 only; overload 3 always starts from this document's own
+[`root()`](root.md)).
+
+## Complexity
+
+1. Linear in the number of members of `object`.
+2. Linear in the number of elements of `array` at or after `idx` (they move one slot over).
+3. Linear in the number of reference tokens of `ptr` and, for each token, in the number of members of the object at
+   that level or the index into the array (as [`at`](../basic_json_view/at.md)), plus the complexity of 1. or 2. for
+   the last token.
+
+## Notes
+
+!!! info "Duplicate keys"
+
+    Overload 1. removes *every* member with `key`, not just the first -- unlike [`set`](set.md), which assigns the
+    first occurrence and drops the rest. This is why it returns a count rather than a single view: there may be
+    more than one member removed, or none.
+
+Like [`set`](set.md) and [`push_back`](push_back.md), `erase` never moves an element's *value*: a view still
+referring to a removed member or element keeps showing what it last held (see [Edits](index.md#edits)) -- it just no
+longer appears when `array`/`object` is read, dumped, or iterated. Removing an element of `array` (2.) does shift the
+*links* to the elements after it, the same way `insert`, `set`, or `push_back` on the same array would; any iterator
+already taken over `array`/`object` is invalidated by an erase, since it was walking the old layout.
+
+## Examples
+
+??? example
+
+    The example below drops a deprecated field and a decommissioned entry from a configuration document -- using all
+    three overloads -- and shows what stays intact that would not with a plain `json`/`ordered_json` value: the order
+    of the fields around the ones removed, and the exact spelling of a number that was never touched.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__erase.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__erase.output"
+    ```
+
+## See also
+
+- [insert](insert.md) - insert an element into an array
+- [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
+- [push_back](push_back.md) - append to an array
+- [root](root.md) - the view of the root value, the starting point of overload 3
+- [`BasicJsonType::erase`](../basic_json/erase.md) - the corresponding function of `basic_json`
+- [Edits](index.md#edits) - what an edit guarantees, for every overload
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/index.md

@@ -19,10 +19,10 @@ it (a copy, or an rvalue `#!cpp std::string` that was moved in); see [`owns_sour
 is move-only: copying a document would either duplicate a potentially large index and text, or leave two documents
 claiming to borrow the same buffer, so it is disabled.
 
-With `#!cpp Editable == true`, the document also offers [`set`](set.md) and [`push_back`](push_back.md) to change
-values in place, see [Edits](#edits) below. The source text itself is never written; a read-only document
-(`#!cpp Editable == false`, the default) does not carry any of the bookkeeping edits need, and calling `set` or
-`push_back` on one fails to compile (`#!cpp static_assert`).
+With `#!cpp Editable == true`, the document also offers [`set`](set.md), [`push_back`](push_back.md),
+[`insert`](insert.md), and [`erase`](erase.md) to change values in place, see [Edits](#edits) below. The source text
+itself is never written; a read-only document (`#!cpp Editable == false`, the default) does not carry any of the
+bookkeeping edits need, and calling any of them on one fails to compile (`#!cpp static_assert`).
 
 ## Template parameters
 
@@ -32,8 +32,8 @@ values in place, see [Edits](#edits) below. The source text itself is never writ
     is checked with a `static_assert`.
 
 `Editable`
-:   whether the document supports [`set`](set.md) and [`push_back`](push_back.md) (optional, `#!cpp false` by
-    default). See [Edits](#edits) below.
+:   whether the document supports [`set`](set.md), [`push_back`](push_back.md), [`insert`](insert.md), and
+    [`erase`](erase.md) (optional, `#!cpp false` by default). See [Edits](#edits) below.
 
 ## Specializations
 
@@ -66,11 +66,15 @@ values in place, see [Edits](#edits) below. The source text itself is never writ
 - [**set**](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers
   to (`#!cpp Editable` documents only)
 - [**push_back**](push_back.md) - append to an array (`#!cpp Editable` documents only)
+- [**insert**](insert.md) - insert an element into an array before a given position (`#!cpp Editable` documents only)
+- [**erase**](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
+  (`#!cpp Editable` documents only)
 
 ## Edits
 
-An editable document (`#!cpp Editable == true`) can be changed after parsing, with [`set`](set.md) and
-[`push_back`](push_back.md); [`json_editable_document`](../json_editable_document.md) and
+An editable document (`#!cpp Editable == true`) can be changed after parsing, with [`set`](set.md),
+[`push_back`](push_back.md), [`insert`](insert.md), and [`erase`](erase.md);
+[`json_editable_document`](../json_editable_document.md) and
 [`ordered_json_editable_document`](../ordered_json_editable_document.md) are the corresponding specializations. A few
 points apply to every edit:
 

docs/mkdocs/docs/api/basic_json_document/insert.md

@@ -0,0 +1,114 @@
+# <small>nlohmann::basic_json_document::</small>insert
+
+```cpp
+template<typename I, typename V>
+view_type insert(view_type array, I idx, V&& value);
+```
+
+Only an **editable** document (`#!cpp Editable == true`, e.g. [`json_editable_document`](../json_editable_document.md))
+has `insert`; calling it on a read-only `basic_json_document` fails to compile (`#!cpp static_assert`).
+
+Inserts `value` into `array` as a new element before position `idx`, which must not be past the end
+(`#!cpp idx <= array.size()`; `#!cpp idx == array.size()` appends, like [`push_back`](push_back.md)). Unlike
+[`push_back`](push_back.md), a [null](../basic_json_view/is_null.md) `array` does *not* first become an empty array:
+`array` must already be an array.
+
+`value` is accepted three ways: a [`basic_json_view`](../basic_json_view/index.md) of *any* document -- read-only or
+editable, and it does not have to be `array`'s own document -- which is copied so that nothing is shared with the
+source document afterward; a `BasicJsonType` value; or anything `BasicJsonType` can be constructed from (numbers,
+strings, `#!cpp bool`, `#!cpp nullptr`, containers, ...).
+
+## Template parameters
+
+`I`
+:   an integral type other than `#!cpp bool`, deduced (overloads taking a `#!cpp bool` or a non-integral type for
+    `idx` do not participate in overload resolution).
+
+`V`
+:   the type of `value`, deduced; see above for what is accepted.
+
+## Parameters
+
+`array` (in)
+:   the array to insert into
+
+`idx` (in)
+:   the position to insert `value` before; a negative value throws (see [Exceptions](#exceptions))
+
+`value` (in)
+:   the value to insert
+
+## Return value
+
+a view of the new element, now holding `value`
+
+## Exception safety
+
+Basic exception safety: `value` is fully encoded -- including the checks below -- into storage owned by the document
+before anything already reachable from [`root()`](root.md) is touched, so a failure while encoding `value` (an
+invalid argument, or `#!cpp std::bad_alloc`) leaves the document completely unchanged, other than memory allocated
+for the encoding that is not reclaimed. A failure of a later allocation -- while `array` switches from its parsed
+layout to a growable block, or while that block grows, see [Notes](#notes) -- can still leave `array` already
+switched to that layout even though `value` itself was not inserted.
+
+## Exceptions
+
+Throws [`type_error.309`](../../home/exceptions.md#jsonexceptiontype_error309) if `array` is not an array -- the same
+message [`BasicJsonType::insert`](../basic_json/insert.md) throws for the same type; a null `array` throws this too
+(see above). Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if `idx` is negative,
+or if `#!cpp idx > array.size()`. Throws
+[`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) ("view does not belong to this
+document") if `array` is a [discarded](../basic_json_view/is_discarded.md) view or a view of a *different* document.
+Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `value` is a
+[discarded](../basic_json_view/is_discarded.md) view or a [discarded](../basic_json/is_discarded.md) `BasicJsonType`
+value, and [`type_error.319`](../../home/exceptions.md#jsonexceptiontype_error319) if `value` is (or contains) a
+binary value -- `BasicJsonType` can hold one, but a `json_document` cannot. Throws
+[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if `value` is (or contains) a string that is
+not valid UTF-8, with the same message [`BasicJsonType::dump()`](../basic_json/dump.md) gives for that string.
+
+## Complexity
+
+Linear in the number of elements of `array` at or after `idx` (they move one slot over), plus time linear in the
+size of `value` to encode it into the document's storage (constant for a scalar, linear in the number of nested
+values for an array or object): like [`push_back`](push_back.md), the elements of `array` move to a growable block
+of links the first time it is inserted into (or [`set`](set.md)/[`push_back`](push_back.md) on), and that block
+grows in amortized constant time; inserting before the end within that block still shifts every later element.
+
+## Notes
+
+Like [`set`](set.md) on a member or an element, `insert` never moves an existing *element's value* -- only where
+`array`'s *links* to its elements live -- so a view of an existing element of `array` stays valid across an
+`insert`, and keeps referring to the same element even though its index shifts. Any iterator already taken over
+`array` is invalidated, since it was walking the old layout. See [Edits](index.md#edits) for what stays valid across
+an edit in general.
+
+## Examples
+
+??? example
+
+    The example below inserts a step into the middle of a deployment plan, without touching the steps that come
+    after it, and shows that a view taken before the insert keeps referring to the same element even though its
+    index shifts -- something a plain `json`/`ordered_json` array, or its `std::vector`-based storage, has no
+    equivalent for.
+
+    ```cpp
+    --8<-- "examples/basic_json_document__insert.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_document__insert.output"
+    ```
+
+## See also
+
+- [push_back](push_back.md) - append to an array
+- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
+- [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
+- [`BasicJsonType::insert`](../basic_json/insert.md) - the corresponding function of `basic_json`
+- [Edits](index.md#edits) - what an edit guarantees, for every overload
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_document/push_back.md

@@ -91,6 +91,8 @@ Like [`set`](set.md) on a member or an element, `push_back` never moves an exist
 ## See also
 
 - [set](set.md) - replace a value, or set an object member, an array element, or the value a JSON pointer refers to
+- [insert](insert.md) - insert an element into an array before a given position
+- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
 - [root](root.md) - the view of the root value
 - [`BasicJsonType::push_back`](../basic_json/push_back.md) - the corresponding function of `basic_json`
 - [Edits](index.md#edits) - what an edit guarantees, for every overload

docs/mkdocs/docs/api/basic_json_document/set.md

@@ -180,6 +180,8 @@ one-node scalar.
 ## See also
 
 - [push_back](push_back.md) - append to an array
+- [insert](insert.md) - insert an element into an array
+- [erase](erase.md) - remove an object member, an array element, or the value a JSON pointer refers to
 - [root](root.md) - the view of the root value, the starting point of overload 4
 - [`basic_json_view::dump`](../basic_json_view/dump.md) - serialize the document, keeping an untouched number's
   spelling with `#!cpp number_format::source`

docs/mkdocs/docs/examples/basic_json_document__erase.cpp

@@ -0,0 +1,38 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json = nlohmann::json;
+using json_editable_document = nlohmann::json_editable_document;
+using json_editable_view = nlohmann::json_editable_view;
+
+int main()
+{
+    // a deprecated field is dropped from a configuration file, and a
+    // decommissioned replica is removed from the list -- "price" keeps its
+    // trailing zero, and the fields around the removed ones keep their order
+    const std::string text = R"({
+  "name": "cache",
+  "legacy_host": "db0",
+  "host": "db1",
+  "price": 19.90,
+  "replicas": ["db2", "db3", "db4"]
+})";
+
+    json_editable_document doc = json_editable_document::parse(text);
+
+    doc.erase(doc.root(), "legacy_host");                                      // (1) an object member
+    doc.erase(doc.root()["replicas"], 1);                                      // (2) an array element ("db3")
+    const std::size_t removed = doc.erase(json::json_pointer("/replicas/0"));  // (3) via a JSON pointer
+
+    std::cout << removed << '\n';
+    std::cout << doc.root().dump(2, ' ', false, json_editable_view::number_format::source) << "\n\n";
+
+    // the same edits on a plain json value: object_t is a std::map, so
+    // parsing already sorted the keys, and dump() rewrites every number to
+    // its shortest form, even "price", which was never touched
+    json plain = json::parse(text);
+    plain.erase("legacy_host");
+    plain["replicas"].erase(1);
+    plain["replicas"].erase(0);
+    std::cout << plain.dump(2) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__erase.output

@@ -0,0 +1,18 @@
+1
+{
+  "name": "cache",
+  "host": "db1",
+  "price": 19.90,
+  "replicas": [
+    "db4"
+  ]
+}
+
+{
+  "host": "db1",
+  "name": "cache",
+  "price": 19.9,
+  "replicas": [
+    "db4"
+  ]
+}

docs/mkdocs/docs/examples/basic_json_document__insert.cpp

@@ -0,0 +1,38 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json = nlohmann::json;
+using json_editable_document = nlohmann::json_editable_document;
+using json_editable_view = nlohmann::json_editable_view;
+
+int main()
+{
+    // a deployment plan -- "budget" is written with a trailing zero that has
+    // no effect on its value
+    const std::string text = R"({
+  "release": "2026.09",
+  "steps": ["build", "test", "deploy"],
+  "budget": 19.90
+})";
+
+    json_editable_document doc = json_editable_document::parse(text);
+
+    const std::size_t deploy_index = 2;
+    const auto deploy = doc.root()["steps"][deploy_index];  // held across the insert
+
+    doc.insert(doc.root()["steps"], deploy_index, "smoke-test"); // insert before "deploy"
+
+    // the held view still refers to "deploy", even though its index moved
+    // from 2 to 3, and nothing else in the document was touched
+    std::cout << deploy.dump() << '\n';
+    std::cout << doc.root().dump(2, ' ', false, json_editable_view::number_format::source) << "\n\n";
+
+    // the same edit on a plain json value: an index held from before the
+    // insert now refers to whatever moved into that slot, and dump()
+    // rewrites "budget" to its shortest form even though it was never
+    // touched
+    json plain = json::parse(text);
+    plain["steps"].insert(plain["steps"].begin() + static_cast<std::ptrdiff_t>(deploy_index), "smoke-test");
+    std::cout << plain["steps"][deploy_index].dump() << '\n';
+    std::cout << plain.dump(2) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_document__insert.output

@@ -0,0 +1,23 @@
+"deploy"
+{
+  "release": "2026.09",
+  "steps": [
+    "build",
+    "test",
+    "smoke-test",
+    "deploy"
+  ],
+  "budget": 19.90
+}
+
+"smoke-test"
+{
+  "budget": 19.9,
+  "release": "2026.09",
+  "steps": [
+    "build",
+    "test",
+    "smoke-test",
+    "deploy"
+  ]
+}

docs/mkdocs/docs/features/json_view.md

@@ -193,11 +193,13 @@ Everything above is read-only: a `json_document`/`json_view` lets you look at a
 not change it. [`basic_json_document<BasicJsonType, true>`](../api/basic_json_document/index.md) -- more conveniently
 spelled [`json_editable_document`](../api/json_editable_document.md) or
 [`ordered_json_editable_document`](../api/ordered_json_editable_document.md) -- also lets you
-[`set`](../api/basic_json_document/set.md) a value and [`push_back`](../api/basic_json_document/push_back.md) onto
-an array, still without ever building a `basic_json` tree for parts you do not touch.
+[`set`](../api/basic_json_document/set.md) a value, [`push_back`](../api/basic_json_document/push_back.md) onto or
+[`insert`](../api/basic_json_document/insert.md) into an array, and [`erase`](../api/basic_json_document/erase.md)
+an object member or an array element, still without ever building a `basic_json` tree for parts you do not touch.
 
 `#!cpp Editable` defaults to `#!cpp false`, so `json_document`/`ordered_json_document` are unaffected -- they carry
-none of the bookkeeping edits need, and calling `set`/`push_back` on one is a compile error, not a runtime one.
+none of the bookkeeping edits need, and calling `set`/`push_back`/`insert`/`erase` on one is a compile error, not a
+runtime one.
 
 ### Why: editing without reformatting
 
@@ -212,8 +214,9 @@ or `ordered_json` value in place lossy. Say you parse a configuration file, patc
 
 An editable document keeps both. [`dump()`](../api/basic_json_view/dump.md) of an edited document writes members in
 document order -- a member [`set`](../api/basic_json_document/set.md) added goes at the end, exactly where it was
-inserted -- and [`number_format::source`](../api/basic_json_view/number_format.md) keeps the exact spelling of
-every number an edit did not itself touch; a number an edit *did* touch is written the way
+inserted, and an [`erase`](../api/basic_json_document/erase.md)d member simply leaves a gap: everything around it
+keeps its place -- and [`number_format::source`](../api/basic_json_view/number_format.md) keeps the exact spelling
+of every number an edit did not itself touch; a number an edit *did* touch is written the way
 [`BasicJsonType::dump()`](../api/basic_json/dump.md) would write it, since there is no source spelling for a brand
 new value.
 
@@ -236,10 +239,11 @@ parsed into for as long as it is not itself replaced. So every [view](../api/bas
 an edit, including a previously obtained [`root()`](../api/basic_json_document/root.md), stays valid and, if it
 still refers to the edited value, sees the edit; a view of a value a later edit drops or replaces just keeps showing
 what it last held. New values go to storage the document allocates and owns on demand. The one thing an edit does
-invalidate is the **iterators** taken over an edited array or object: the first time one of its elements is set or
-appended to, its elements move from the parsed, fixed layout to a growable block of links so that
-[`push_back`](../api/basic_json_document/push_back.md) can later grow it in amortized constant time -- existing
-elements are not touched, but an iterator that was walking the old layout no longer matches. A string obtained with
+invalidate is the **iterators** taken over an edited array or object: the first time one of its elements is set,
+appended to, inserted into, or erased, its elements move from the parsed, fixed layout to a growable block of links
+so that [`push_back`](../api/basic_json_document/push_back.md) can later grow it in amortized constant time --
+existing elements are not touched, but an iterator that was walking the old layout no longer matches. A string
+obtained with
 [`get_string()`](../api/basic_json_view/get_string.md) is unaffected either way and stays valid across further
 edits. See [`basic_json_document`'s Edits](../api/basic_json_document/index.md#edits) for the details, and
 [`set`'s Exception safety](../api/basic_json_document/set.md#exception-safety) for what an edit guarantees if it
@@ -251,7 +255,7 @@ the index is described in the [architecture overview](../home/architecture.md#no
 | | [`json`](../api/json.md) / [`ordered_json`](../api/ordered_json.md) | [SAX interface](parsing/sax_interface.md) | [`json_document`](../api/json_document.md) / [`json_view`](../api/json_view.md) | [`json_editable_document`](../api/json_editable_document.md) / [`json_editable_view`](../api/json_editable_view.md) |
 |---|---|---|---|---|
 | **Ownership** | owns every value | owns nothing; you decide what to keep, in your handler | borrows or owns the *text*; the index is always owned by the document | same as `json_document`; edits go to storage the document owns |
-| **Mutability** | freely mutable | not applicable (a one-shot event stream) | read-only | [`set`](../api/basic_json_document/set.md)/[`push_back`](../api/basic_json_document/push_back.md) edit in place; the source text is never rewritten |
+| **Mutability** | freely mutable | not applicable (a one-shot event stream) | read-only | [`set`](../api/basic_json_document/set.md)/[`push_back`](../api/basic_json_document/push_back.md)/[`insert`](../api/basic_json_document/insert.md)/[`erase`](../api/basic_json_document/erase.md) edit in place; the source text is never rewritten |
 | **What you get** | a full tree you can read, write, and keep as long as you like | a sequence of callbacks; whatever your handler builds from them | a flat index plus, on demand, [`materialize()`](../api/basic_json_view/materialize.md)d `json`/`ordered_json` values for the parts you actually use | the same, plus [`dump()`](../api/basic_json_view/dump.md) of an edited document that keeps the member order and, with [`number_format::source`](../api/basic_json_view/number_format.md), the spelling of every untouched number |
 | **Typical use** | general-purpose JSON handling: config, request/response bodies you build or modify, anything you hold onto | validating or projecting a text into your own data structure without ever holding the whole thing as JSON | large or high-volume input where you only need part of it, or need it repeatedly, and can keep the source text (or a copy) alive for as long as the document lives | a document you read, patch a few fields of, and write back -- a configuration file, for instance -- where the rest of it should come back exactly as it was |
 

docs/mkdocs/mkdocs.yml

@@ -233,6 +233,8 @@ nav:
           - 'Overview': api/basic_json_document/index.md
           - '(Constructor)': api/basic_json_document/basic_json_document.md
           - 'accept': api/basic_json_document/accept.md
+          - 'erase': api/basic_json_document/erase.md
+          - 'insert': api/basic_json_document/insert.md
           - 'is_discarded': api/basic_json_document/is_discarded.md
           - 'memory_usage': api/basic_json_document/memory_usage.md
           - 'node_count': api/basic_json_document/node_count.md

include/nlohmann/detail/view/edit.hpp

@@ -227,6 +227,62 @@ class editor
         return View(&m_doc, slot);
     }
 
+    /// insert into an array before position idx (idx <= size()); returns a
+    /// view of the new element
+    template<typename V>
+    View insert(const View& array, std::size_t idx, V&& value)
+    {
+        node* const a = own(array);
+        if (a->kind != static_cast<std::uint8_t>(value_t::array))
+        {
+            throw_type_error(309, "cannot use insert() with ", array.type_name());
+        }
+        check_index(idx, a->len + 1);
+        const encoded e = encode(std::forward<V>(value));
+        node* const slot = new_slot(e);
+        node* const h = block_of(m_doc, a, 1);
+        std::memmove(h + 2 + idx, h + 1 + idx, (h->next - 1 - idx) * sizeof(node));
+        make_link(h[1 + idx], slot);
+        ++h->next;
+        ++h->len;
+        ++a->len;
+        return View(&m_doc, slot);
+    }
+
+    /// remove all members with this key; returns their number
+    std::size_t erase(const View& object, string_view_t key)
+    {
+        node* const o = own(object);
+        if (o->kind != static_cast<std::uint8_t>(value_t::object))
+        {
+            throw_type_error(307, "cannot use erase() with ", object.type_name());
+        }
+        for (const node* k = nav::first(m_doc, o), *end = nav::end(m_doc, o); k != end; k = document_data::after(k + 1))
+        {
+            if (key_equals(*k, key))
+            {
+                return erase_members(o, key, false);
+            }
+        }
+        return 0;
+    }
+
+    /// remove an array element
+    void erase(const View& array, std::size_t idx)
+    {
+        node* const a = own(array);
+        if (a->kind != static_cast<std::uint8_t>(value_t::array))
+        {
+            throw_type_error(307, "cannot use erase() with ", array.type_name());
+        }
+        check_index(idx, a->len);
+        node* const h = block_of(m_doc, a, 0);
+        std::memmove(h + 1 + idx, h + 2 + idx, (h->next - 2 - idx) * sizeof(node));
+        --h->next;
+        --h->len;
+        --a->len;
+    }
+
   private:
     /// an encoded value: a scalar node, or the root of a new array/object
     struct encoded

include/nlohmann/json_view.hpp

@@ -1061,6 +1061,45 @@ class basic_json_document
         return editor().push_back(array, std::forward<V>(value));
     }
 
+    /// insert into an array before position idx (idx <= size()); returns a
+    /// view of the new element
+    template < typename I, typename V, typename std::enable_if < std::is_integral<I>::value && !std::is_same<I, bool>::value, int >::type = 0 >
+    view_type insert(view_type array, I idx, V && value)
+    {
+        return editor().insert(array, index(idx), std::forward<V>(value));
+    }
+
+    /// remove all members with this key; returns their number
+    std::size_t erase(view_type object, string_view_t key)
+    {
+        return editor().erase(object, key);
+    }
+
+    /// remove an array element
+    template < typename I, typename std::enable_if < std::is_integral<I>::value && !std::is_same<I, bool>::value, int >::type = 0 >
+    void erase(view_type array, I idx)
+    {
+        editor().erase(array, index(idx));
+    }
+
+    /// remove the value at a JSON pointer; returns the number of removed
+    /// values
+    std::size_t erase(const json_pointer& ptr)
+    {
+        if (ptr.empty())
+        {
+            detail::view::throw_out_of_range(405, "JSON pointer has no parent");
+        }
+        const view_type parent = root().at(ptr.parent_pointer());
+        const auto& token = ptr.back();
+        if (parent.is_array())
+        {
+            erase(parent, pointer_index(token));
+            return 1;
+        }
+        return erase(parent, string_view_t(token.data(), token.size()));
+    }
+
   private:
     using input_kind = detail::view::input_kind;
 

single_include/nlohmann/json_view.hpp

@@ -3228,6 +3228,62 @@ class editor
         return View(&m_doc, slot);
     }
 
+    /// insert into an array before position idx (idx <= size()); returns a
+    /// view of the new element
+    template<typename V>
+    View insert(const View& array, std::size_t idx, V&& value)
+    {
+        node* const a = own(array);
+        if (a->kind != static_cast<std::uint8_t>(value_t::array))
+        {
+            throw_type_error(309, "cannot use insert() with ", array.type_name());
+        }
+        check_index(idx, a->len + 1);
+        const encoded e = encode(std::forward<V>(value));
+        node* const slot = new_slot(e);
+        node* const h = block_of(m_doc, a, 1);
+        std::memmove(h + 2 + idx, h + 1 + idx, (h->next - 1 - idx) * sizeof(node));
+        make_link(h[1 + idx], slot);
+        ++h->next;
+        ++h->len;
+        ++a->len;
+        return View(&m_doc, slot);
+    }
+
+    /// remove all members with this key; returns their number
+    std::size_t erase(const View& object, string_view_t key)
+    {
+        node* const o = own(object);
+        if (o->kind != static_cast<std::uint8_t>(value_t::object))
+        {
+            throw_type_error(307, "cannot use erase() with ", object.type_name());
+        }
+        for (const node* k = nav::first(m_doc, o), *end = nav::end(m_doc, o); k != end; k = document_data::after(k + 1))
+        {
+            if (key_equals(*k, key))
+            {
+                return erase_members(o, key, false);
+            }
+        }
+        return 0;
+    }
+
+    /// remove an array element
+    void erase(const View& array, std::size_t idx)
+    {
+        node* const a = own(array);
+        if (a->kind != static_cast<std::uint8_t>(value_t::array))
+        {
+            throw_type_error(307, "cannot use erase() with ", array.type_name());
+        }
+        check_index(idx, a->len);
+        node* const h = block_of(m_doc, a, 0);
+        std::memmove(h + 1 + idx, h + 2 + idx, (h->next - 2 - idx) * sizeof(node));
+        --h->next;
+        --h->len;
+        --a->len;
+    }
+
   private:
     /// an encoded value: a scalar node, or the root of a new array/object
     struct encoded
@@ -6240,6 +6296,45 @@ class basic_json_document
         return editor().push_back(array, std::forward<V>(value));
     }
 
+    /// insert into an array before position idx (idx <= size()); returns a
+    /// view of the new element
+    template < typename I, typename V, typename std::enable_if < std::is_integral<I>::value && !std::is_same<I, bool>::value, int >::type = 0 >
+    view_type insert(view_type array, I idx, V && value)
+    {
+        return editor().insert(array, index(idx), std::forward<V>(value));
+    }
+
+    /// remove all members with this key; returns their number
+    std::size_t erase(view_type object, string_view_t key)
+    {
+        return editor().erase(object, key);
+    }
+
+    /// remove an array element
+    template < typename I, typename std::enable_if < std::is_integral<I>::value && !std::is_same<I, bool>::value, int >::type = 0 >
+    void erase(view_type array, I idx)
+    {
+        editor().erase(array, index(idx));
+    }
+
+    /// remove the value at a JSON pointer; returns the number of removed
+    /// values
+    std::size_t erase(const json_pointer& ptr)
+    {
+        if (ptr.empty())
+        {
+            detail::view::throw_out_of_range(405, "JSON pointer has no parent");
+        }
+        const view_type parent = root().at(ptr.parent_pointer());
+        const auto& token = ptr.back();
+        if (parent.is_array())
+        {
+            erase(parent, pointer_index(token));
+            return 1;
+        }
+        return erase(parent, string_view_t(token.data(), token.size()));
+    }
+
   private:
     using input_kind = detail::view::input_kind;
 

tests/benchmarks/json_view/README.md

@@ -7,7 +7,7 @@ users ask when they pick a library. They are not built by CMake or run by CI.
 
 ## Reproducing the numbers
 
-`compare.py` builds both programs against `include/` of this checkout, runs them, and writes the results together with
+`compare.py` builds the programs against `include/` of this checkout, runs them, and writes the results together with
 everything needed to reproduce them to `results/<date>-<host>.md` (and `.csv`): the date, the commit, the CPU, the
 OS, the compiler, the flags, and the versions of all libraries.
 
@@ -52,6 +52,12 @@ JSON-RPC request (`rpc`):
 `bench_corpus.cpp` runs parse, traverse, and dump on any list of files, so that no library is tuned to a handful of
 documents.
 
+`bench_edit.cpp` measures read-modify-write: parse, apply the same logical edits with each library's own API, and
+serialize (compact). Workloads: `patch` (a handful of edits at fixed places) and `update` (edits in every record).
+An editable `json_document` edits in place; yyjson copies its immutable document into a mutable one first
+(`yyjson_doc_mut_copy`); Boost.JSON and `json::parse` build mutable DOMs; simdjson cannot edit a document. All
+outputs are checked to describe the same value.
+
 Before anything is timed, all engines must accept each document and agree on the traversal: the number of values, the
 bytes of all strings and keys, and the sum of all numbers. All engines run interleaved in every round, and the best
 round is reported, as time and as a factor of the `json_view` time (below 1 means faster than `json_view`).

tests/benchmarks/json_view/bench_edit.cpp

@@ -0,0 +1,575 @@
+//     __ _____ _____ _____
+//  __|  |   __|     |   | |  JSON for Modern C++ (supporting code)
+// |  |  |__   |  |  | | | |  version 3.12.0
+// |_____|_____|_____|_|___|  https://github.com/nlohmann/json
+//
+// SPDX-FileCopyrightText: 2013-2026 Niels Lohmann <https://nlohmann.me>
+// SPDX-License-Identifier: MIT
+
+// Read-modify-write benchmark: parse a document, apply the same logical edits
+// with each library's own API, and serialize it (compact).
+//
+//   json_view     json_editable_document: edits in place, unchanged values stay in the index
+//   yyjson        yyjson_read + yyjson_doc_mut_copy (the way to edit a parsed document)
+//   Boost.JSON    parse into a mutable DOM (monotonic resource, precise numbers), serialize
+//   json::parse   nlohmann::json today
+// simdjson has no mutable document and is not part of this comparison.
+//
+// Workloads:
+//   patch   a handful of edits at fixed places (scalars, a new member, a new array element)
+//   update  edits in every record (twitter: 100 statuses, citm: 243 performances,
+//           canada: 480 rings, jeopardy: 216,930 questions): set scalars, erase a
+//           member, add a member (canada: replace the first point of every ring)
+//
+// Build: see README.md (same flags as bench_view.cpp).
+#include <nlohmann/json_view.hpp>
+
+#if JSON_VIEW_BENCH_BOOST
+    #include <boost/json.hpp>
+    #include <boost/json/src.hpp>
+#endif
+#include <yyjson.h>
+
+#include <algorithm>
+#include <chrono>
+#include <cstdio>
+#include <cstdlib>
+#include <fstream>
+#include <functional>
+#include <sstream>
+
+using nlohmann::json;
+using nlohmann::json_editable_document;
+using nlohmann::json_editable_view;
+#if JSON_VIEW_BENCH_BOOST
+    namespace bj = boost::json;
+#endif
+
+static volatile std::size_t g_sink;
+
+// ---------------- json_view ----------------
+
+static std::string edit_view(const std::string& name, const std::string& s, bool update)
+{
+    json_editable_document d = json_editable_document::parse(s);
+    const json_editable_view r = d.root();
+    if (name == "twitter")
+    {
+        if (update)
+        {
+            std::int64_t i = 0;
+            for (const json_editable_view st : r["statuses"])
+            {
+                d.set(st, "retweet_count", i++);
+                d.set(st, "favorited", true);
+                d.set(st, "text", "redacted");
+                d.erase(st, "entities");
+                d.set(st, "edited", true);
+            }
+        }
+        else
+        {
+            d.set(r["search_metadata"], "count", 200);
+            d.set(r["statuses"][0], "text", "patched");
+            d.set(r["statuses"][0]["user"], "followers_count", 1);
+            d.set(r["statuses"][99], "favorited", true);
+            d.set(r, "patched", true);
+        }
+    }
+    else if (name == "citm_catalog")
+    {
+        if (update)
+        {
+            for (const json_editable_view p : r["performances"])
+            {
+                d.set(p, "name", "performance");
+                d.set(p, "start", p["start"].get<std::int64_t>() + 1);
+                d.erase(p, "seatMapImage");
+                d.set(p, "edited", true);
+            }
+        }
+        else
+        {
+            d.set(r["events"]["138586341"], "name", "patched");
+            d.set(r["performances"][0], "start", 0);
+            d.set(r["venueNames"], "PLEYEL_PLEYEL", "Salle");
+            d.set(r, "patched", true);
+        }
+    }
+    else if (name == "canada")
+    {
+        const json_editable_view coords = r["features"][0]["geometry"]["coordinates"];
+        if (update)
+        {
+            for (const json_editable_view ring : coords)
+            {
+                d.set(ring, 0, json::array({0.5, 0.5}));
+            }
+        }
+        else
+        {
+            d.set(r["features"][0]["properties"], "name", "patched");
+            d.set(r, "type", "FeatureCollection2");
+            d.set(coords[0], 0, json::array({0.0, 0.0}));
+        }
+    }
+    else if (name == "jeopardy")
+    {
+        if (update)
+        {
+            for (const json_editable_view q : r)
+            {
+                d.set(q, "value", "$1");
+                d.erase(q, "air_date");
+            }
+        }
+        else
+        {
+            d.set(r[0], "value", "$0");
+            d.set(r[100000], "answer", "patched");
+            d.set(r[216929], "round", "x");
+            d.push_back(r, json::object({{"category", "NEW"}, {"value", "$5"}}));
+        }
+    }
+    else if (name == "status")
+    {
+        d.set(r, "retweet_count", 1);
+        d.set(r["user"], "name", "x");
+    }
+    else if (name == "rpc")
+    {
+        d.set(r, "id", 4);
+        d.set(r["params"], "subtrahend", 24);
+    }
+    return r.dump();
+}
+
+// ---------------- nlohmann::json ----------------
+
+static std::string edit_json(const std::string& name, const std::string& s, bool update)
+{
+    json r = json::parse(s);
+    if (name == "twitter")
+    {
+        if (update)
+        {
+            std::int64_t i = 0;
+            for (auto& st : r["statuses"])
+            {
+                st["retweet_count"] = i++;
+                st["favorited"] = true;
+                st["text"] = "redacted";
+                st.erase("entities");
+                st["edited"] = true;
+            }
+        }
+        else
+        {
+            r["search_metadata"]["count"] = 200;
+            r["statuses"][0]["text"] = "patched";
+            r["statuses"][0]["user"]["followers_count"] = 1;
+            r["statuses"][99]["favorited"] = true;
+            r["patched"] = true;
+        }
+    }
+    else if (name == "citm_catalog")
+    {
+        if (update)
+        {
+            for (auto& p : r["performances"])
+            {
+                p["name"] = "performance";
+                p["start"] = p["start"].get<std::int64_t>() + 1;
+                p.erase("seatMapImage");
+                p["edited"] = true;
+            }
+        }
+        else
+        {
+            r["events"]["138586341"]["name"] = "patched";
+            r["performances"][0]["start"] = 0;
+            r["venueNames"]["PLEYEL_PLEYEL"] = "Salle";
+            r["patched"] = true;
+        }
+    }
+    else if (name == "canada")
+    {
+        json& coords = r["features"][0]["geometry"]["coordinates"];
+        if (update)
+        {
+            for (auto& ring : coords)
+            {
+                ring[0] = json::array({0.5, 0.5});
+            }
+        }
+        else
+        {
+            r["features"][0]["properties"]["name"] = "patched";
+            r["type"] = "FeatureCollection2";
+            coords[0][0] = json::array({0.0, 0.0});
+        }
+    }
+    else if (name == "jeopardy")
+    {
+        if (update)
+        {
+            for (auto& q : r)
+            {
+                q["value"] = "$1";
+                q.erase("air_date");
+            }
+        }
+        else
+        {
+            r[0]["value"] = "$0";
+            r[100000]["answer"] = "patched";
+            r[216929]["round"] = "x";
+            r.push_back(json::object({{"category", "NEW"}, {"value", "$5"}}));
+        }
+    }
+    else if (name == "status")
+    {
+        r["retweet_count"] = 1;
+        r["user"]["name"] = "x";
+    }
+    else if (name == "rpc")
+    {
+        r["id"] = 4;
+        r["params"]["subtrahend"] = 24;
+    }
+    return r.dump();
+}
+
+// ---------------- yyjson ----------------
+
+static std::string edit_yyjson(const std::string& name, const std::string& s, bool update)
+{
+    yyjson_doc* idoc = yyjson_read(s.data(), s.size(), 0);
+    yyjson_mut_doc* d = yyjson_doc_mut_copy(idoc, nullptr);
+    yyjson_doc_free(idoc);
+    yyjson_mut_val* r = yyjson_mut_doc_get_root(d);
+    auto get = [](yyjson_mut_val * o, const char* k)
+    {
+        return yyjson_mut_obj_get(o, k);
+    };
+    if (name == "twitter")
+    {
+        yyjson_mut_val* sts = get(r, "statuses");
+        if (update)
+        {
+            std::size_t idx, max;
+            yyjson_mut_val* st;
+            std::int64_t i = 0;
+            yyjson_mut_arr_foreach(sts, idx, max, st)
+            {
+                yyjson_mut_set_sint(get(st, "retweet_count"), i++);
+                yyjson_mut_set_bool(get(st, "favorited"), true);
+                yyjson_mut_set_str(get(st, "text"), "redacted");
+                yyjson_mut_obj_remove_key(st, "entities");
+                yyjson_mut_obj_add_bool(d, st, "edited", true);
+            }
+        }
+        else
+        {
+            yyjson_mut_set_sint(get(get(r, "search_metadata"), "count"), 200);
+            yyjson_mut_val* s0 = yyjson_mut_arr_get(sts, 0);
+            yyjson_mut_set_str(get(s0, "text"), "patched");
+            yyjson_mut_set_sint(get(get(s0, "user"), "followers_count"), 1);
+            yyjson_mut_set_bool(get(yyjson_mut_arr_get(sts, 99), "favorited"), true);
+            yyjson_mut_obj_add_bool(d, r, "patched", true);
+        }
+    }
+    else if (name == "citm_catalog")
+    {
+        if (update)
+        {
+            std::size_t idx, max;
+            yyjson_mut_val* p;
+            yyjson_mut_arr_foreach(get(r, "performances"), idx, max, p)
+            {
+                yyjson_mut_set_str(get(p, "name"), "performance");
+                yyjson_mut_val* start = get(p, "start");
+                yyjson_mut_set_sint(start, yyjson_mut_get_sint(start) + 1);
+                yyjson_mut_obj_remove_key(p, "seatMapImage");
+                yyjson_mut_obj_add_bool(d, p, "edited", true);
+            }
+        }
+        else
+        {
+            yyjson_mut_set_str(get(get(get(r, "events"), "138586341"), "name"), "patched");
+            yyjson_mut_set_sint(get(yyjson_mut_arr_get(get(r, "performances"), 0), "start"), 0);
+            yyjson_mut_set_str(get(get(r, "venueNames"), "PLEYEL_PLEYEL"), "Salle");
+            yyjson_mut_obj_add_bool(d, r, "patched", true);
+        }
+    }
+    else if (name == "canada")
+    {
+        yyjson_mut_val* f0 = yyjson_mut_arr_get(get(r, "features"), 0);
+        yyjson_mut_val* coords = get(get(f0, "geometry"), "coordinates");
+        if (update)
+        {
+            static const double half[2] = {0.5, 0.5};
+            std::size_t idx, max;
+            yyjson_mut_val* ring;
+            yyjson_mut_arr_foreach(coords, idx, max, ring)
+            {
+                yyjson_mut_arr_replace(ring, 0, yyjson_mut_arr_with_real(d, half, 2));
+            }
+        }
+        else
+        {
+            static const double zero[2] = {0.0, 0.0};
+            yyjson_mut_set_str(get(get(f0, "properties"), "name"), "patched");
+            yyjson_mut_set_str(get(r, "type"), "FeatureCollection2");
+            yyjson_mut_arr_replace(yyjson_mut_arr_get(coords, 0), 0, yyjson_mut_arr_with_real(d, zero, 2));
+        }
+    }
+    else if (name == "jeopardy")
+    {
+        if (update)
+        {
+            std::size_t idx, max;
+            yyjson_mut_val* q;
+            yyjson_mut_arr_foreach(r, idx, max, q)
+            {
+                yyjson_mut_set_str(get(q, "value"), "$1");
+                yyjson_mut_obj_remove_key(q, "air_date");
+            }
+        }
+        else
+        {
+            yyjson_mut_set_str(get(yyjson_mut_arr_get(r, 0), "value"), "$0");
+            yyjson_mut_set_str(get(yyjson_mut_arr_get(r, 100000), "answer"), "patched");
+            yyjson_mut_set_str(get(yyjson_mut_arr_get(r, 216929), "round"), "x");
+            yyjson_mut_val* o = yyjson_mut_obj(d);
+            yyjson_mut_obj_add_str(d, o, "category", "NEW");
+            yyjson_mut_obj_add_str(d, o, "value", "$5");
+            yyjson_mut_arr_append(r, o);
+        }
+    }
+    else if (name == "status")
+    {
+        yyjson_mut_set_sint(get(r, "retweet_count"), 1);
+        yyjson_mut_set_str(get(get(r, "user"), "name"), "x");
+    }
+    else if (name == "rpc")
+    {
+        yyjson_mut_set_sint(get(r, "id"), 4);
+        yyjson_mut_set_sint(get(get(r, "params"), "subtrahend"), 24);
+    }
+    std::size_t n = 0;
+    char* out = yyjson_mut_write(d, 0, &n);
+    std::string result(out, n);
+    std::free(out);
+    yyjson_mut_doc_free(d);
+    return result;
+}
+
+#if JSON_VIEW_BENCH_BOOST
+// ---------------- Boost.JSON ----------------
+
+static std::string edit_boost(const std::string& name, const std::string& s, bool update)
+{
+    bj::monotonic_resource mr;
+    bj::parse_options opt;
+    opt.numbers = bj::number_precision::precise; // correctly rounded, like the others
+    bj::value v = bj::parse(s, &mr, opt);
+    bj::object* const obj = v.if_object(); // nullptr for jeopardy (an array)
+    if (name == "twitter")
+    {
+        bj::array& sts = (*obj)["statuses"].as_array();
+        if (update)
+        {
+            std::int64_t i = 0;
+            for (auto& e : sts)
+            {
+                bj::object& st = e.as_object();
+                st["retweet_count"] = i++;
+                st["favorited"] = true;
+                st["text"] = "redacted";
+                st.erase("entities");
+                st["edited"] = true;
+            }
+        }
+        else
+        {
+            (*obj)["search_metadata"].as_object()["count"] = 200;
+            bj::object& s0 = sts[0].as_object();
+            s0["text"] = "patched";
+            s0["user"].as_object()["followers_count"] = 1;
+            sts[99].as_object()["favorited"] = true;
+            (*obj)["patched"] = true;
+        }
+    }
+    else if (name == "citm_catalog")
+    {
+        if (update)
+        {
+            for (auto& e : (*obj)["performances"].as_array())
+            {
+                bj::object& p = e.as_object();
+                p["name"] = "performance";
+                p["start"] = p["start"].as_int64() + 1;
+                p.erase("seatMapImage");
+                p["edited"] = true;
+            }
+        }
+        else
+        {
+            (*obj)["events"].as_object()["138586341"].as_object()["name"] = "patched";
+            (*obj)["performances"].as_array()[0].as_object()["start"] = 0;
+            (*obj)["venueNames"].as_object()["PLEYEL_PLEYEL"] = "Salle";
+            (*obj)["patched"] = true;
+        }
+    }
+    else if (name == "canada")
+    {
+        bj::object& f0 = (*obj)["features"].as_array()[0].as_object();
+        bj::array& coords = f0["geometry"].as_object()["coordinates"].as_array();
+        if (update)
+        {
+            for (auto& ring : coords)
+            {
+                ring.as_array()[0] = bj::array({0.5, 0.5});
+            }
+        }
+        else
+        {
+            f0["properties"].as_object()["name"] = "patched";
+            (*obj)["type"] = "FeatureCollection2";
+            coords[0].as_array()[0] = bj::array({0.0, 0.0});
+        }
+    }
+    else if (name == "jeopardy")
+    {
+        bj::array& a = v.as_array();
+        if (update)
+        {
+            for (auto& e : a)
+            {
+                bj::object& q = e.as_object();
+                q["value"] = "$1";
+                q.erase("air_date");
+            }
+        }
+        else
+        {
+            a[0].as_object()["value"] = "$0";
+            a[100000].as_object()["answer"] = "patched";
+            a[216929].as_object()["round"] = "x";
+            a.push_back(bj::object({{"category", "NEW"}, {"value", "$5"}}));
+        }
+    }
+    else if (name == "status")
+    {
+        (*obj)["retweet_count"] = 1;
+        (*obj)["user"].as_object()["name"] = "x";
+    }
+    else if (name == "rpc")
+    {
+        (*obj)["id"] = 4;
+        (*obj)["params"].as_object()["subtrahend"] = 24;
+    }
+    return bj::serialize(v);
+}
+#endif
+
+// ---------------- harness ----------------
+
+static std::string slurp(const std::string& p)
+{
+    std::ifstream f(p, std::ios::binary);
+    std::stringstream ss;
+    ss << f.rdbuf();
+    return ss.str();
+}
+
+int main(int argc, char** argv)
+{
+    if (argc < 2)
+    {
+        std::fprintf(stderr, "usage: %s <json_test_data directory> [rounds] [document]\n", argv[0]);
+        return 1;
+    }
+    const std::string T = std::string(argv[1]) + "/";
+    const int rounds = argc > 2 ? std::atoi(argv[2]) : 20;
+    const std::string only = argc > 3 ? argv[3] : "";
+    struct doc
+    {
+        std::string name, text;
+        int batch;
+    };
+    std::vector<doc> docs;
+    for (const char* f :
+            {"nativejson-benchmark/twitter.json", "nativejson-benchmark/citm_catalog.json", "nativejson-benchmark/canada.json", "jeopardy/jeopardy.json"
+            })
+    {
+        std::string n = std::string(f).substr(std::string(f).find('/') + 1);
+        docs.push_back({n.substr(0, n.size() - 5), slurp(T + f), 1});
+    }
+    docs.push_back({"status", json::parse(docs[0].text)["statuses"][0].dump(), 200});
+    docs.push_back({"rpc", R"({"jsonrpc": "2.0", "method": "subtract", "params": {"minuend": 42, "subtrahend": 23}, "id": 3})", 5000});
+
+    using fn = std::string (*)(const std::string&, const std::string&, bool);
+    const std::vector<std::pair<std::string, fn>> engines =
+    {
+        {"json_view", edit_view}, {"yyjson", edit_yyjson},
+#if JSON_VIEW_BENCH_BOOST
+        {"Boost.JSON", edit_boost},
+#endif
+        {"json::parse", edit_json}
+    };
+
+    std::FILE* csv = std::fopen("bench_edit.csv", "w");
+    std::fprintf(csv, "doc,bytes,workload,engine,ns\n");
+    for (const auto& dc : docs)
+    {
+        if (!only.empty() && dc.name != only)
+        {
+            continue;
+        }
+        for (const bool update :
+                {
+                    false, true
+                })
+        {
+            if (update && (dc.name == "status" || dc.name == "rpc"))
+            {
+                continue;
+            }
+            // all engines must produce the same value
+            const json expected = json::parse(edit_json(dc.name, dc.text, update));
+            bool ok = true;
+            for (const auto& e : engines)
+            {
+                ok = ok && json::parse(e.second(dc.name, dc.text, update)) == expected;
+            }
+            std::vector<double> best(engines.size(), 1e300);
+            const int r = dc.text.size() > 10000000 ? std::max(3, rounds / 4) : rounds;
+            for (int i = 0; i < r; ++i)
+            {
+                for (std::size_t k = 0; k < engines.size(); ++k)
+                {
+                    const auto t0 = std::chrono::steady_clock::now();
+                    for (int b = 0; b < dc.batch; ++b)
+                    {
+                        g_sink = engines[k].second(dc.name, dc.text, update).size();
+                    }
+                    const double ns = std::chrono::duration<double, std::nano>(std::chrono::steady_clock::now() - t0).count() / dc.batch;
+                    best[k] = std::min(best[k], ns);
+                }
+            }
+            const char* wl = update ? "update" : "patch";
+            std::printf("%-13s %-7s %s", dc.name.c_str(), wl, ok ? "" : "[OUTPUT MISMATCH] ");
+            for (std::size_t k = 0; k < engines.size(); ++k)
+            {
+                const double us = best[k] / 1e3;
+                std::printf("  %s %.*fus (%.2fx)", engines[k].first.c_str(), us < 10 ? 3 : (us < 1000 ? 1 : 0), us, best[k] / best[0]);
+                std::fprintf(csv, "%s,%zu,%s,%s,%.1f\n", dc.name.c_str(), dc.text.size(), wl, engines[k].first.c_str(), best[k]);
+            }
+            std::printf("\n");
+            std::fflush(stdout);
+        }
+    }
+    std::fclose(csv);
+}

tests/benchmarks/json_view/compare.py

@@ -9,7 +9,7 @@
 
 """Compare json_view with yyjson, simdjson, Boost.JSON, and json::parse.
 
-Builds bench_view.cpp and bench_corpus.cpp against the include/ directory of
+Builds bench_view.cpp, bench_corpus.cpp, and bench_edit.cpp against the include/ directory of
 this checkout, runs them, and writes the results with everything needed to
 reproduce them (date, commit, CPU, OS, compiler, library versions, flags) to
 results/<date>-<host>.md and .csv next to this script.
@@ -245,7 +245,7 @@ def main():
             objects.append(obj)
 
     binaries = {}
-    for bench in ['bench_view', 'bench_corpus']:
+    for bench in ['bench_view', 'bench_corpus', 'bench_edit']:
         exe = os.path.join(args.build_dir, bench)
         run([cxx] + flags + include + [os.path.join(HERE, bench + '.cpp')] + objects + link + ['-o', exe])
         binaries[bench] = exe
@@ -257,6 +257,8 @@ def main():
                                 capture_output=True, text=True).stdout
     outputs['bench_corpus'] = run([binaries['bench_corpus']] + corpus, cwd=args.build_dir,
                                   capture_output=True, text=True).stdout
+    outputs['bench_edit'] = run([binaries['bench_edit'], args.data, str(max(1, args.rounds // 2))], cwd=args.build_dir,
+                                capture_output=True, text=True).stdout
     for name, text in outputs.items():
         print(text)
 
@@ -288,7 +290,7 @@ def main():
             f.write(f'\n## {name}\n\n```\n{text.rstrip()}\n```\n')
     with open(stem + '.csv', 'w', encoding='utf-8') as out:
         out.write(''.join(f'# {key}: {value}\n' for key, value in meta))
-        for name in ['bench_view', 'bench_corpus']:
+        for name in ['bench_view', 'bench_corpus', 'bench_edit']:
             path = os.path.join(args.build_dir, name + '.csv')
             if os.path.isfile(path):
                 with open(path, encoding='utf-8') as f:

tests/src/unit-json_view_edit.cpp

@@ -278,12 +278,45 @@ TEST_CASE("json_view edits: differential")
                     d.set(tv, key, v);
                     j[p][key] = v;
                 }
+                else if (op == 6 && target.is_object() && !target.empty()) // erase a member
+                {
+                    const std::string key = std::next(target.begin(), r(static_cast<int>(target.size()))).key();
+                    if (r(2) == 0)
+                    {
+                        d.erase(tv, key);
+                    }
+                    else
+                    {
+                        d.erase(p / key);
+                    }
+                    j[p].erase(key);
+                }
                 else if (op == 7 && (target.is_array() || target.is_null())) // push_back
                 {
                     const ordered_json v = random_value(2);
                     d.push_back(tv, v);
                     j[p].push_back(v);
                 }
+                else if (op == 8 && target.is_array()) // insert
+                {
+                    const auto i = static_cast<std::size_t>(r(static_cast<int>(target.size()) + 1));
+                    const ordered_json v = random_value(2);
+                    d.insert(tv, i, v);
+                    j[p].insert(j[p].begin() + static_cast<std::ptrdiff_t>(i), v);
+                }
+                else if (op == 9 && target.is_array() && !target.empty()) // erase an element
+                {
+                    const auto i = static_cast<std::size_t>(r(static_cast<int>(target.size())));
+                    if (r(2) == 0)
+                    {
+                        d.erase(tv, i);
+                    }
+                    else
+                    {
+                        d.erase(p / i);
+                    }
+                    j[p].erase(i);
+                }
                 else if (op == 10 && target.is_array() && !target.empty()) // assign an element
                 {
                     const auto i = static_cast<std::size_t>(r(static_cast<int>(target.size())));
@@ -350,6 +383,13 @@ TEST_CASE("json_view edits: errors")
     CHECK_THROWS_WITH_AS(d.set(root["a"], 2, 1), "[json.exception.out_of_range.401] array index 2 is out of range", json::out_of_range&);
     CHECK_THROWS_WITH_AS(d.set(root["a"], -1, 1), "[json.exception.out_of_range.401] array index -1 is out of range", json::out_of_range&);
     CHECK_THROWS_WITH_AS(d.push_back(root["o"], 1), "[json.exception.type_error.308] cannot use push_back() with object", json::type_error&);
+    CHECK_THROWS_WITH_AS(d.insert(root["n"], 0, 1), "[json.exception.type_error.309] cannot use insert() with number", json::type_error&);
+    CHECK_THROWS_WITH_AS(d.insert(root["a"], 3, 1), "[json.exception.out_of_range.401] array index 3 is out of range", json::out_of_range&);
+    CHECK_THROWS_WITH_AS(d.erase(root["n"], "k"), "[json.exception.type_error.307] cannot use erase() with number", json::type_error&);
+    CHECK_THROWS_WITH_AS(d.erase(root["o"], 0), "[json.exception.type_error.307] cannot use erase() with object", json::type_error&);
+    CHECK_THROWS_WITH_AS(d.erase(root["a"], 2), "[json.exception.out_of_range.401] array index 2 is out of range", json::out_of_range&);
+    CHECK_THROWS_WITH_AS(d.erase(json::json_pointer("")), "[json.exception.out_of_range.405] JSON pointer has no parent", json::out_of_range&);
+    CHECK_THROWS_WITH_AS(d.erase(json::json_pointer("/missing/x")), "[json.exception.out_of_range.403] key 'missing' not found", json::out_of_range&);
     CHECK_THROWS_WITH_AS(d.set(json::json_pointer("/a/01"), 1), "[json.exception.parse_error.106] parse error: array index '01' must not begin with '0'", json::parse_error&);
     CHECK_THROWS_WITH_AS(d.set(root, json_editable_view()), "[json.exception.type_error.302] type must be a value, but is discarded", json::type_error&);
     CHECK_THROWS_WITH_AS(d.set(root, json::binary({1, 2})), "[json.exception.type_error.319] cannot store a binary value in a json_document", json::type_error&);
@@ -390,6 +430,27 @@ TEST_CASE("json_view edits: views and values")
         CHECK(inner.get<int>() == 5);
     }
 
+    SECTION("views keep referring to their value")
+    {
+        json_editable_document d = json_editable_document::parse(R"({"a": [10, 20, 30], "b": {"c": "text"}})");
+        const json_editable_view a = d.root()["a"];
+        const json_editable_view twenty = a[1];
+        const json_editable_view c = d.root()["b"]["c"];
+        d.insert(a, 0, 5);
+        d.push_back(a, 40);
+        CHECK(twenty.get<int>() == 20);
+        CHECK(a[2].get<int>() == 20);
+        d.erase(a, 2);
+        CHECK(twenty.get<int>() == 20); // an erased value keeps its last value
+        d.set(c, 7);
+        CHECK(c.get<int>() == 7); // a held view sees an assignment
+        d.set(d.root()["b"], json::array({1, 2}));
+        CHECK(d.root()["b"].dump() == "[1,2]");
+        CHECK(d.root().dump() == R"({"a":[5,10,30,40],"b":[1,2]})");
+        CHECK(d.root()["a"][0].source_offset() == static_cast<std::size_t>(-1)); // a new value
+        CHECK(d.root()["a"][1].source_offset() != static_cast<std::size_t>(-1));
+    }
+
     SECTION("strings stay valid while more edits come")
     {
         json_editable_document d = json_editable_document::parse("[]");
@@ -433,6 +494,10 @@ TEST_CASE("json_view edits: views and values")
         d.set(json::json_pointer("/x/3"), 4); // the size of the array appends too
         d.set(json::json_pointer("/y"), false);
         CHECK(d.root().dump() == R"({"x":[1,2,3,4],"y":false})");
+        CHECK(d.erase(json::json_pointer("/x/0")) == 1);
+        CHECK(d.erase(json::json_pointer("/y")) == 1);
+        CHECK(d.erase(json::json_pointer("/nothing")) == 0);
+        CHECK(d.root().dump() == R"({"x":[2,3,4]})");
     }
 
     SECTION("duplicate keys")
@@ -440,6 +505,9 @@ TEST_CASE("json_view edits: views and values")
         json_editable_document d = json_editable_document::parse(R"({"a": 1, "b": 2, "a": 3})");
         d.set(d.root(), "a", 4); // the first member is assigned, the others dropped
         CHECK(d.root().dump() == R"({"a":4,"b":2})");
+        d = json_editable_document::parse(R"({"a": 1, "b": 2, "a": 3})");
+        CHECK(d.erase(d.root(), "a") == 2);
+        CHECK(d.root().dump() == R"({"b":2})");
     }
 
     SECTION("values from other documents")
@@ -472,7 +540,9 @@ TEST_CASE("json_view edits: views and values")
         d.set(d.root(), "new", 1); // appended: the members move, the lookup is linear
         CHECK(d.root()["new"].get<int>() == 1);
         CHECK(d.root()["k199"].get<int>() == 199);
-        CHECK(d.root().size() == 201);
+        d.erase(d.root(), "k0");
+        CHECK(!d.root().contains("k0"));
+        CHECK(d.root().size() == 200);
     }
 
     SECTION("reuse and memory")