docs: explain signed zero in the diff() round-trip exceptions (#5944)

Spell out that numbers comparing equal produce no operation even if one is
zero and the other negative zero, in diff.md and features/json_patch.md.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and GitHub committed 2026-10-27 17:16:08 +01:00
1 parent 78a0687147
commit eb8f675bc9
2 files changed
+7 -5

No files matched your search

+4 -3
View File
@@ -19,9 +19,10 @@ The equality holds up to [`operator==`](operator_eq.md), so it has the following
- A value that is not equal to itself cannot round-trip. This applies to `NaN` (also nested in an array or object) and - 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](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is to [discarded](is_discarded.md) values: `diff` emits a `replace` operation for them. A `NaN` in the patch is
serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`. serialized as `#!json null`, so a patch that was dumped and parsed again would set `#!json null`.
- Numbers that compare equal produce no operation, even if their types or signs differ: `diff(1, 1.0)`, - Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is
`diff(1u, 1)` (unsigned and signed integer) and `diff(0.0, -0.0)` all return `#!json []`. The patched value is then negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and
the `source` and keeps its number type. `diff(0.0, -0.0)` (positive and negative zero) all return `#!json []`. The patched value is then the `source` and
keeps its number type and sign.
## Parameters ## Parameters
+3 -2
View File
@@ -78,8 +78,9 @@ flowchart LR
- `NaN` and [discarded](../api/basic_json/is_discarded.md) values are not equal to themselves, so the invariant - `NaN` and [discarded](../api/basic_json/is_discarded.md) values are not equal to themselves, so the invariant
cannot hold for them. `diff` emits a `replace` operation for such a value, and a `NaN` in a patch is serialized cannot hold for them. `diff` emits a `replace` operation for such a value, and a `NaN` in a patch is serialized
as `#!json null`. as `#!json null`.
- Numbers that compare equal produce no operation even if their types differ: `diff(1, 1.0)`, `diff(1u, 1)`, and - Numbers that compare equal produce no operation even if their types differ or if one is zero and the other is
`diff(0.0, -0.0)` return `#!json []`, so the patched value keeps the number type of *source*. negative zero: `diff(1, 1.0)`, `diff(1u, 1)`, and `diff(0.0, -0.0)` return `#!json []`, so the patched value
keeps the number type and sign of *source*.
- A [binary value](binary_values.md) in a patch is serialized as an object - A [binary value](binary_values.md) in a patch is serialized as an object
(`#!json {"bytes":[...],"subtype":null}`), so a patch that was dumped and parsed again no longer holds a binary (`#!json {"bytes":[...],"subtype":null}`), so a patch that was dumped and parsed again no longer holds a binary
value. value.