# nlohmann::basic_json::merge_patch

```
void merge_patch(const basic_json& apply_patch);
```

The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.

The function implements the following algorithm from Section 2 of [RFC 7396 (JSON Merge Patch)](https://tools.ietf.org/html/rfc7396):

```
define MergePatch(Target, Patch):
  if Patch is an Object:
    if Target is not an Object:
      Target = {} // Ignore the contents and set it to an empty Object
    for each Name/Value pair in Patch:
      if Value is null:
        if Name exists in Target:
          remove the Name/Value pair from Target
      else:
        Target[Name] = MergePatch(Target[Name], Value)
    return Target
  else:
    return Patch
```

Thereby, `Target` is the current object; that is, the patch is applied to the current value.

## Parameters

`apply_patch` (in) : the patch to apply

## Exception safety

Basic guarantee: if an exception is thrown during the operation, the JSON value may be partially modified.

## Complexity

Linear in the total number of values (including nested ones) in `apply_patch`, times the cost of a key-based object operation (looking up, adding, or erasing a member): 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`, patching an object that has `n` members with a patch that has `m` members therefore takes O(n·m). The cost also includes one copy of `apply_patch` (see the notes below).

## Notes

- `apply_patch` may be `*this` itself or refer to a value contained in `*this` (for example, a subobject returned by `(*this)[key]`); it is read as it was when `merge_patch()` was called, before any modification of `*this`. To make this possible, the function copies `apply_patch` before it modifies `*this`, so the cost includes one copy of the patch.
- A merge patch uses `null` to remove a member, so it cannot set a member to `null`: applying `{"a":null}` to `{"a":1}` gives `{}`.
- Arrays are not merged: an array in the patch replaces the target value as a whole, and a `null` inside an array is kept as an element. `null` members of the target that the patch does not mention are preserved.
- A `null` in the patch only removes a member; it does not prevent the creation of the enclosing objects. Applying `{"a":{"b":null}}` to `{}` gives `{"a":{}}` (see example 15 in Appendix A of the RFC).
- If `apply_patch` is not an object, it replaces the target as a whole. In particular, a `null` patch turns the target into `null`. If `apply_patch` is an object and the target is not, the target is first replaced by an empty object, so applying `{}` to `1` gives `{}`.
- A merge patch cannot express every change; for example, it cannot reorder array elements or remove a specific array element. Use [JSON Patch](https://json.nlohmann.me/features/json_patch/index.md) ([RFC 6902](https://tools.ietf.org/html/rfc6902)) for that. [`merge_diff`](https://json.nlohmann.me/api/basic_json/merge_diff/index.md) has a matching limitation, see its notes.
- A [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) value is treated like any other non-object value: a discarded `apply_patch` turns the target into a discarded value, and an object patch replaces a discarded target by an object as described above.

## Examples

Example

The following code shows how a JSON Merge Patch is applied to a JSON document.

```
#include <iostream>
#include <nlohmann/json.hpp>
#include <iomanip> // for std::setw

using nlohmann::json;
using namespace nlohmann::literals;

int main()
{
    // the original document
    json document = R"({
                "title": "Goodbye!",
                "author": {
                    "givenName": "John",
                    "familyName": "Doe"
                },
                "tags": [
                    "example",
                    "sample"
                ],
                "content": "This will be unchanged"
            })"_json;

    // the patch
    json patch = R"({
                "title": "Hello!",
                "phoneNumber": "+01-123-456-7890",
                "author": {
                    "familyName": null
                },
                "tags": [
                    "example"
                ]
            })"_json;

    // apply the patch
    document.merge_patch(patch);

    // output original and patched document
    std::cout << std::setw(4) << document << '\n';
}
```

Output:

```
{
    "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)
- [patch](https://json.nlohmann.me/api/basic_json/patch/index.md) apply a JSON patch
- [merge_diff](https://json.nlohmann.me/api/basic_json/merge_diff/index.md) creates a diff as a JSON Merge Patch

## Version history

- Added in version 3.1.0.
- Fixed use of freed or relocated memory when `apply_patch` is `*this` or refers to a value contained in `*this`, in version 3.13.0 unreleased.