From eb8f675bc9f28a3c9edc2708a4e5dfabb379edbc Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Tue, 27 Oct 2026 17:16:08 +0100 Subject: [PATCH] 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 --- docs/mkdocs/docs/api/basic_json/diff.md | 7 ++++--- docs/mkdocs/docs/features/json_patch.md | 5 +++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/mkdocs/docs/api/basic_json/diff.md b/docs/mkdocs/docs/api/basic_json/diff.md index 655261a3d..162882cdb 100644 --- a/docs/mkdocs/docs/api/basic_json/diff.md +++ b/docs/mkdocs/docs/api/basic_json/diff.md @@ -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 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`. -- 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 `#!json []`. The patched value is then - the `source` and keeps its number type. +- Numbers that compare equal produce no operation, even if their types differ or if one is zero and the other is + negative zero: `diff(1, 1.0)` (integer and floating-point), `diff(1u, 1)` (unsigned and signed integer) and + `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 diff --git a/docs/mkdocs/docs/features/json_patch.md b/docs/mkdocs/docs/features/json_patch.md index 3329c6cba..ea22b4e15 100644 --- a/docs/mkdocs/docs/features/json_patch.md +++ b/docs/mkdocs/docs/features/json_patch.md @@ -78,8 +78,9 @@ flowchart LR - `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 as `#!json null`. - - Numbers that compare equal produce no operation even if their types differ: `diff(1, 1.0)`, `diff(1u, 1)`, and - `diff(0.0, -0.0)` return `#!json []`, so the patched value keeps the number type of *source*. + - Numbers that compare equal produce no operation even if their types differ or if one is zero and the other is + 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 (`#!json {"bytes":[...],"subtype":null}`), so a patch that was dumped and parsed again no longer holds a binary value.