deploy: 40a62947d3

api/basic_json/merge_diff/index.md

@@ -0,0 +1,136 @@
+# nlohmann::basic_json::merge_diff
+
+```
+static basic_json merge_diff(const basic_json& source,
+                             const basic_json& target);
+```
+
+Creates a [JSON Merge Patch](https://tools.ietf.org/html/rfc7396) so that value `source` can be changed into the value `target` by calling the [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) function. The patch contains only what differs: changed and added members with their new values, and removed members with the value `null`. Nested objects are compared member by member; any other value that differs, including an array, is replaced as a whole.
+
+For two JSON values `source` and `target`, where `target` contains no object member whose value is `null`, the following code always yields `true`:
+
+```
+basic_json patched = source;
+patched.merge_patch(merge_diff(source, target));
+patched == target;
+```
+
+## Parameters
+
+`source` (in) : JSON value to compare from
+
+`target` (in) : JSON value to compare against
+
+## Return value
+
+a JSON Merge Patch to convert the `source` to `target`
+
+## Exception safety
+
+Strong guarantee: `source` and `target` are never modified.
+
+## Complexity
+
+Linear in the total number of values (including nested ones) in `source` and `target`, times the cost of a key-based object operation (looking up a key, or adding one to the patch): logarithmic for [`json`](https://json.nlohmann.me/api/json/index.md), and linear for [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md) (see [`ordered_map` complexity](https://json.nlohmann.me/api/ordered_map/#complexity)). For `ordered_json`, diffing two objects with `n` and `m` members therefore takes O((n+m)²).
+
+## Notes
+
+- A merge patch uses `null` to remove a member, so it cannot set a member to `null`. As in RFC 7396, a `null` member of `target` is treated as absent: the patch removes the member from `source` instead of setting it to `null`. A member that is `null` in both `source` and `target` is unchanged and left out of the patch, so `source` keeps it.
+- A merge patch cannot reorder object members, and [`merge_patch`](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) appends added members at the end. For [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), the patched value therefore has the same members as `target`, but not necessarily in the same order, and may compare unequal to it. The patch lists changed and removed members in the order of `source`, followed by added members in the order of `target`.
+
+## Examples
+
+Example
+
+The following code shows how a JSON Merge Patch is created as a diff for two JSON values.
+
+```
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+using namespace nlohmann::literals;
+
+int main()
+{
+    // the source document
+    json source = R"(
+        {
+            "title": "Goodbye!",
+            "author": {
+                "givenName": "John",
+                "familyName": "Doe"
+            },
+            "tags": [
+                "example",
+                "sample"
+            ],
+            "content": "This will be unchanged"
+        }
+    )"_json;
+
+    // the target document
+    json target = R"(
+        {
+            "title": "Hello!",
+            "author": {
+                "givenName": "John"
+            },
+            "tags": [
+                "example"
+            ],
+            "content": "This will be unchanged",
+            "phoneNumber": "+01-123-456-7890"
+        }
+    )"_json;
+
+    // create the patch
+    json patch = json::merge_diff(source, target);
+
+    // roundtrip
+    json patched_source = source;
+    patched_source.merge_patch(patch);
+
+    // output patch and roundtrip result
+    std::cout << std::setw(4) << patch << "\n\n"
+              << std::setw(4) << patched_source << std::endl;
+}
+```
+
+Output:
+
+```
+{
+    "author": {
+        "familyName": null
+    },
+    "phoneNumber": "+01-123-456-7890",
+    "tags": [
+        "example"
+    ],
+    "title": "Hello!"
+}
+
+{
+    "author": {
+        "givenName": "John"
+    },
+    "content": "This will be unchanged",
+    "phoneNumber": "+01-123-456-7890",
+    "tags": [
+        "example"
+    ],
+    "title": "Hello!"
+}
+```
+
+## See also
+
+- [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396)
+- [merge_patch](https://json.nlohmann.me/api/basic_json/merge_patch/index.md) applies a JSON Merge Patch
+- [diff](https://json.nlohmann.me/api/basic_json/diff/index.md) creates a diff as a JSON Patch
+
+## Version history
+
+- Added in version 3.13.0 unreleased.