mirror of https://github.com/nlohmann/json.git synced 2026-10-02 20:50:32 +00:00

Files

T

Niels Lohmann 63c10a51fc Review and extend the documentation, and check it in CI (#5638 )

* Review and extend the documentation, and check it in CI

A review of all documentation pages found factual errors, dead links,
missing cross-references, and gaps in examples. This fixes them and adds
checks so the same problems are caught automatically.

Fixes:
- wrong signatures and version histories (operator!= C++20 member,
  binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...)
- stale descriptions (number parsing since #5283, UBJSON table, SAX
  example that no longer compiled, tsl::ordered_map advice)
- dead internal and external links; repology.org badges (the domain is
  suspended) replaced by badges that query the registries directly
- deprecation notes link the migration guide; the guide itself fixed

Additions:
- "See also" sections, cross-references, 25 runnable examples, 12
  Mermaid diagrams, new API pages for json_pointer::operator<=> and
  byte_container_with_subtype::operator==/!=
- landing page, guides for untrusted input and performance
- "unreleased" badge after versions newer than the latest release

Checks:
- strict documentation build (broken links/anchors fail it); CI and
  the publish workflow fetch the full history the build needs
- weekly external link check, Mermaid syntax check in CI
- check_structure.py: example titles, heading levels, alt texts,
  header links, docset index coverage; its unused-example check works
  again
- all examples produce the same output on every platform

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

* Keep the customer links that could not be fixed

A dead link on the customers page is still the evidence of where the
use of the library was documented. Keep the original URLs of the entries
without a working replacement (Marne, Cisco Webex Desk Camera, Philips
Hue, CyberArk) and exclude exactly these URLs from the link check.

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

* Correct the duplicate-key recipe's claim about SAX positions

The SAX interface's key() receives no position either; only parse_error()
does. Also note that the recipe does not report the path to the repeated
key (see discussion #5085).

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

* Say the library is available as a single header and mention json_fwd.hpp

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

* Correct documentation errors found while hunting for bugs

- patch/patch_inplace: list the JSON pointer errors parse_error.106-109
  and out_of_range.402/404, and quote the actual parse_error.105 message.
- unflatten: list parse_error.106/107/108 and out_of_range.404.
- to_bson: list out_of_range.415 (binary subtype above 255) and note
  that 412 and 415 are new in 3.13.0.
- to_string: state that string_t must be convertible to std::string, also
  in the StringType requirements table.
- JSON Lines: a `while (input >> j)` loop also throws after the last value
  for concatenated JSON values; show a loop that works for both.
- BON8: a string gets 0xFF only if nothing follows it in the message; a
  string at the end of an array or object is ended by 0xFE.
- custom_string_type.hpp: add operator+=(char), which the "Always
  required" list asks for (json_pointer::to_string, flatten, unflatten,
  and diff did not compile), and an ADL int_to_string for diff and items.

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

* Cache the release headers with functools.lru_cache

Codacy (Pylint) flagged the mutable default argument that header() used
as its cache. functools.lru_cache keeps the same memoization without it.
The script's output is unchanged.

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

---------

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

2026-10-02 11:32:15 +02:00

5.6 KiB

Raw Blame History

nlohmann::basic_json::patch_inplace

void patch_inplace(const basic_json& json_patch);

JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JSON document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from the patch. This function applies a JSON patch in place and returns void.

Parameters

json_patch (in): JSON patch document

Exception safety

No guarantees, value may be corrupted by an unsuccessful patch operation.

Exceptions

Throws parse_error.104 if the JSON patch does not consist of an array of objects.
Throws parse_error.105 if the JSON patch is malformed (e.g., mandatory attributes are missing); example: "operation 'add' must have member 'path'".
Throws out_of_range.401 if an array index is out of range.
Throws parse_error.106 if an array index in a "path" or "from" member begins with '0'; example: "array index '01' must not begin with '0'".
Throws parse_error.107 if a "path" or "from" member is not empty and does not begin with a slash (/); example: "JSON pointer must be empty or begin with '/' - was: 'a'".
Throws parse_error.108 if a tilde (~) in a "path" or "from" member is not followed by 0 or 1; example: "escape character '~' must be followed with '0' or '1'".
Throws parse_error.109 if an array index in a "path" or "from" member is not a number; example: "array index 'foo' is not a number".
Throws out_of_range.402 if the array index - is used where an existing element is required (the "path" of "replace", the "from" of "move" and "copy"); example: "array index '-' (3) is out of range".
Throws out_of_range.403 if a JSON pointer inside the patch could not be resolved successfully in the current JSON value; example: "key baz not found".
Throws out_of_range.404 if a reference token of a JSON pointer inside the patch cannot be resolved, e.g., - in a "remove" operation or 1a for an array; example: "unresolved reference token '-'".
Throws out_of_range.405 if JSON pointer has no parent ("add", "remove", "move")
Throws out_of_range.411 if an "add" operation's target location has a parent that is neither an object nor an array.
Throws out_of_range.413 if a "remove" operation's target location has a parent that is neither an object nor an array.
Throws out_of_range.414 if a "move" operation's "from" location is a proper prefix of its "path" location.
Throws other_error.501 if "test" operation was unsuccessful.

Complexity

Linear in the size of the JSON value and the length of the JSON patch. As usually the patch affects only a fraction of the JSON value, the complexity can usually be neglected.

Notes

Unlike patch, patch_inplace applies the operation "in place" and no copy of the JSON value is created. That makes it faster for large documents by avoiding the copy. However, the JSON value might be corrupted if the function throws an exception.

Examples

??? example "Example: apply a JSON patch in place"

The following code shows how a JSON patch is applied to a value.
 
```cpp
--8<-- "examples/patch_inplace.cpp"
```

Output:

```json
--8<-- "examples/patch_inplace.output"
```

??? example "Example: out_of_range.403 exception with a partially applied patch"

The following code shows a patch whose first operation succeeds and whose second operation fails. Because
`patch_inplace` applies each operation directly to the value, the first operation's effect is still visible after
the exception is caught, unlike [`patch`](patch.md).

```cpp
--8<-- "examples/patch_inplace__exception.cpp"
```

Output:

```json
--8<-- "examples/patch_inplace__exception.output"
```

Version history

Added in version 3.11.0.
Added out_of_range.411 and stopped relying on an internal assertion when an "add" operation's target location has a non-object/non-array parent in version 3.13.0.
Added out_of_range.413 and stopped silently ignoring a "remove" operation whose target location has a non-object/non-array parent in version 3.13.0.
Added out_of_range.414 and rejected a "move" operation whose "from" location is a proper prefix of its "path" location instead of silently producing a corrupted result in version 3.13.0.

5.6 KiB Raw Blame History