json/docs/mkdocs/docs/api/basic_json/patch.md

nlohmann::basic_json::patch

basic_json patch(const basic_json& json_patch) const;

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.

Parameters

json_patch (in)

JSON patch document

Return value

patched document

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the JSON value.

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 ("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. A "test" operation whose "path" does not exist is unsuccessful, too: the failed lookup is reported as a failed test, even if the operation has no "value" member (which would otherwise be parse_error.105). Which of the two errors is reported for this combination depends on the order in which the operands of a comparison are evaluated, so do not rely on it.

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

The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value.

Duplicate member names inside an operation object are resolved by the parser before the patch is applied (the last one is kept, see object_t), so #!json {"op": "add", "op": "remove", "path": "/a"} is a remove operation.

Examples

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

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

Output:

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

??? example "Example: out_of_range.414 exception"

The following code shows how a "move" operation whose "from" location is a proper prefix of its "path" location is
rejected, and how the original document is left unchanged because the patch is applied to a copy.

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

Output:

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

See also

• RFC 6902 (JSON Patch) - specification of JSON Patch
• RFC 6901 (JSON Pointer) - specification of JSON Pointer
• patch_inplace - applies a JSON Patch without creating a copy of the document
• merge_patch - applies a JSON Merge Patch
• JSON Patch and Diff - the article on JSON Patch
• JSON Pointer - the addressing scheme used for patch paths

Version history

• Added in version 2.0.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. This includes a null parent, which was previously silently converted to an object, 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.
• Throws parse_error.109 instead of out_of_range.404 for a one-character array index that is not a digit (e.g., /x) in version 3.13.0, as it already did for longer ones.