deploy: 94fe31eb9b

api/basic_json/diff/index.md

@@ -2,23 +2,31 @@
 
 ```
 static basic_json diff(const basic_json& source,
-                       const basic_json& target);
+                       const basic_json& target,
+                       const string_t& path = "");
 ```
 
 Creates a [JSON Patch](http://jsonpatch.com) so that value `source` can be changed into the value `target` by calling [`patch`](https://json.nlohmann.me/api/basic_json/patch/index.md) function.
 
-For two JSON values `source` and `target`, the following code always yields `true`:
+For two JSON values `source` and `target`, the following code yields `true`:
 
 ```
 source.patch(diff(source, target)) == target;
 ```
 
+The equality holds up to [`operator==`](https://json.nlohmann.me/api/basic_json/operator_eq/index.md), so it has the following exceptions:
+
+- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and to [discarded](https://json.nlohmann.me/api/basic_json/is_discarded/index.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is serialized as `null`, so a patch that was dumped and parsed again would set `null`.
+- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`, `diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `[]`. The patched value is then the `source` and keeps its number type.
+
 ## Parameters
 
 `source` (in) : JSON value to compare from
 
 `target` (in) : JSON value to compare against
 
+`path` (in) : a prefix that is put verbatim in front of the `path` member of every operation (default: `""`, which addresses the root of the value). The prefix is neither escaped nor validated: `diff(1, 2, "abc")` yields an operation with the `path` `abc`, which is not a valid JSON Pointer. Use it with a valid JSON Pointer such as `/root` and escape `~` and `/` in its reference tokens (see [JSON Pointer](https://json.nlohmann.me/features/json_pointer/index.md)).
+
 ## Return value
 
 a JSON patch to convert the `source` to `target`
@@ -29,11 +37,17 @@ Strong guarantee: `source` and `target` are never modified.
 
 ## Complexity
 
-Linear in the lengths of `source` and `target`.
+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 in an object): 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)²) when their keys do not line up (e.g., a key was added or the keys are in a different order). The size of the patch is proportional to the number of operations times the length of their paths, so a small change deep inside a value yields a long `path`.
 
 ## Notes
 
-Currently, only `remove`, `add`, and `replace` operations are generated.
+- Currently, only `remove`, `add`, and `replace` operations are generated.
+- The patch is correct, but not guaranteed to be minimal. For instance, `diff([1,2,3], [0,1,2,3])` yields three `replace` operations and one `add` operation instead of a single insertion.
+- Differences between two arrays are reported index by index. Elements that were added at the end of the array are added with `add` operations on the path `/-` (appended in order), and elements that were removed are removed with `remove` operations from the highest index down to the lowest, so that the remaining indices stay valid.
+- For objects, the operations for the members of `source` come first (`replace`, `remove`, or the operations for nested values, in the iteration order of `source`), followed by `add` operations for the members that only `target` has.
+- For [`ordered_json`](https://json.nlohmann.me/api/ordered_json/index.md), objects with the same keys in a different order are different. As a patch cannot reorder members, `diff` removes all keys of the `source` object and adds them again in the order of the `target`.
+- If `source` and `target` differ as a whole (e.g., different types), the patch consists of a single `replace` operation for the root of the value, i.e., with the `path` `""` (or the given `path` prefix).
+- The `value` members of the patch hold copies of values of `target`. A [binary](https://json.nlohmann.me/features/binary_values/index.md) value has no JSON representation: when a patch that contains one is serialized, it becomes an object such as `{"bytes":[1,3],"subtype":null}`, so a parsed patch no longer holds a binary value (and would set that object instead).
 
 ## Examples
 
@@ -46,7 +60,7 @@ The following code shows how a JSON patch is created as a diff for two JSON valu
 #include <iomanip>
 #include <nlohmann/json.hpp>
 
-using json = nlohmann::json;
+using nlohmann::json;
 using namespace nlohmann::literals;
 
 int main()
@@ -77,7 +91,7 @@ int main()
 
     // output patch and roundtrip result
     std::cout << std::setw(4) << patch << "\n\n"
-              << std::setw(4) << patched_source << std::endl;
+              << std::setw(4) << patched_source << '\n';
 }
 ```