Skip to content

# nlohmann::basic_json::diff

    static basic_json diff(const basic_json& source,
                           const basic_json& target);

Creates a JSON Patch so that value `source` can be changed into the value `target` by calling `patch` function.

For two JSON values `source` and `target`, the following code yields always `true`:

    source.patch(diff(source, target)) == target;

## Parameters

`source` (in)
  JSON value to compare from
`target` (in)
  JSON value to compare against

## Return value

a JSON patch to convert the `source` to `target`

## Exception safety

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

## Complexity

Linear in the lengths of `source` and `target`.

## Notes

Currently, only `remove`, `add`, and `replace` operations are generated.

## Examples

Example

The following code shows how a JSON 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"(
            {
                "baz": "qux",
                "foo": "bar"
            }
        )"_json;

        // the target document
        json target = R"(
            {
                "baz": "boo",
                "hello": [
                    "world"
                ]
            }
        )"_json;

        // create the patch
        json patch = json::diff(source, target);

        // roundtrip
        json patched_source = source.patch(patch);

        // output patch and roundtrip result
        std::cout << std::setw(4) << patch << "\n\n"
                  << std::setw(4) << patched_source << std::endl;
    }

Output:

    [
        {
            "op": "replace",
            "path": "/baz",
            "value": "boo"
        },
        {
            "op": "remove",
            "path": "/foo"
        },
        {
            "op": "add",
            "path": "/hello",
            "value": [
                "world"
            ]
        }
    ]

    {
        "baz": "boo",
        "hello": [
            "world"
        ]
    }

## See also

- RFC 6902 (JSON Patch)

## Version history

- Added in version 2.0.0.

Last update: May 1, 2022
Back to top