nlohmann::basic_json::patch¶

basic_jsonpatch(constbasic_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 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.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 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¶

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.

Examples¶

Example

The following code shows how a JSON patch is applied to a value.

#include<iostream>
#include<iomanip>
#include<nlohmann/json.hpp>
usingjson=nlohmann::json;
usingnamespacenlohmann::literals;
intmain()
{
// the original document
jsondoc=R"(
 {
 "baz": "qux",
 "foo": "bar"
 }
)"_json;
// the patch
jsonpatch=R"(
 [
 { "op": "replace", "path": "/baz", "value": "boo" },
 { "op": "add", "path": "/hello", "value": ["world"] },
 { "op": "remove", "path": "/foo"}
 ]
)"_json;
// apply the patch
jsonpatched_doc=doc.patch(patch);
// output original and patched document
std::cout<<std::setw(4)<<doc<<"\n\n"
<<std::setw(4)<<patched_doc<<std::endl;
}

Output:

{
"baz":"qux",
"foo":"bar"
}
{
"baz":"boo",
"hello":[
"world"
]
}

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.12.x.