[nlohmann]

What & why

diff() descends into both values once per nesting level, and compares them with operator== on every level on the way, which recurses as well. Values nested deeply enough terminate the process with SIGSEGV: 25,000 levels on an 8 MiB stack. parse() accepts such values without complaint. On such a chain the per-level comparisons and per-level path strings also made diff() quadratic in time and memory. Reported in #5393.

Part of the same series as #5546, see the table there.

The change

Like merge_patch() and dump(), diff() now bounds its descent with a depth count:

• The first detail::recursion_depth_limit() (128, shared with the other operations) levels: the recursive algorithm diffs them exactly as before, now named diff_recursively() and given a depth parameter. It keeps its per-level operator== shortcut, which is safe since Fix stack overflow and exponential runtime when comparing nested values #5390 made comparisons non-recursive.
• Deeper: diff_iteratively() walks the rest on an explicit stack, emitting the same operations in the same order. It doesn't compare arrays and objects with operator== up front, since doing that on every level would be quadratic in the depth and equal ones yield no operations anyway. It keeps the path in one buffer instead of a new string per level.

An earlier version of this PR scanned the source first (nesting_exceeds) because operator== still recursed; that scan and its cost are gone.

Cost

None measurable. Median of 15 runs, clang -O2:

workload	develop	this PR
twitter.json, equal	0.19 ms	0.18 ms
twitter.json, every 97th leaf changed	4.87 ms	5.13 ms
citm_catalog.json, equal	0.29 ms	0.29 ms
citm_catalog.json, every 97th leaf changed	28.2 ms	28.2 ms
canada.json, equal	0.52 ms	0.53 ms
canada.json, every 97th leaf changed	7.83 ms	7.93 ms

(The scan-based version took 0.24 / 0.38 / 0.86 ms on the equal documents.)

Verification

• Identical patches: a differential against develop on 12,042 diffs (8,524 non-empty) is identical, in C++11 and C++20. It covers random json and ordered_json pairs with NaN, discarded values, 1 vs 1.0, binary values, reordered members, arrays of different lengths, and a custom root path with escaping, plus chains crossing the bound up to 400 levels deep.
• After the rework: another differential against develop on 800 random json and ordered_json pairs with chains 100–180 levels deep, 110 of whose operations lie deeper than 128 levels: byte-identical patches, and every patch reproduces its target.
• Deep values: 1,000,000 levels of nested arrays diff fine on a 1 MiB stack (re-checked after the rework); develop crashes at 100,000.
• Tests:
  • At every depth up to 300, the patch must reproduce the target (for json and ordered_json, including reordered members). A difference deep inside must be exactly one replace operation, with the right path.
  • Values nested 100,000 levels deep are diffed.
  • Three mutants of the iterative walk fail 623–1,775 assertions: dropping the added members, dropping the removed elements, and not restoring the path.
• The JSON Patch conformance tests from the test data pass unchanged.
• make amalgamate + make check-amalgamation; no new findings from the clang-tidy checks CI runs, or -Weverything.

Public API impact

No breaking changes. diff()'s signature and results are unchanged; the helpers are private.

---

• The changes are described in detail, both the what and why.
• If applicable, an existing issue is referenced. (Stack overflow in diff(), merge_patch(), and flatten() due to unbounded recursion #5393)
• The Code coverage remained at 100%. A test case for every new line of code.
• If applicable, the documentation is updated. (nothing documents the recursion)
• The source code is amalgamated by running make amalgamate.

🤖 Generated with Claude Code

[nlohmann]

#5639 found that diff()'s fast/slow-path check (the code this PR moves into diff_object_keys()) sends every object type except an insertion-ordered one (e.g. ordered_json) through the slow (remove-everything, re-add-everything) path whenever an added key sorts before an existing common key, even though a plain std::map never needs its members reordered. Fixed for develop in #5691 by requiring the order check only when detail::is_ordered_map<object_t>::value is true.

This branch has the same condition (currently at diff_object_keys(), "if (common_keys_source_order == common_keys_target_order && new_keys_form_suffix)") and needs the equivalent change so the bug isn't reintroduced when this PR merges:

-        if (common_keys_source_order == common_keys_target_order && new_keys_form_suffix)
+        // Only an object type that keeps its members in insertion order,
+        // such as nlohmann::ordered_map, can need reordering: patch() appends
+        // a new member at the end of such an object. Any other object type
+        // places its members itself - std::map in key order, a hash map in an
+        // order its operator== ignores - so a member-by-member diff always
+        // reproduces target there.
+        if (!detail::is_ordered_map<object_t>::value
+                || (common_keys_source_order == common_keys_target_order && new_keys_form_suffix))
         {
             // fast path: order of common keys already matches (or the
             // object_t's iteration order does not depend on

---

This comment was written by Claude Code on behalf of @nlohmann.

[nlohmann]

Merged develop (795ce4e). Conflict in diff()'s object handling: develop's #5691 (take the fast path for every object type except an insertion-ordered one, and only track target key order for such types) edited the inline code this PR moved into diff_object_keys(). The merge keeps the PR's split and re-applies #5691 inside diff_object_keys(), so the recursive and the iterative walk both get it (checked: the #5639 example gives 1 op for json and 5 for ordered_json at depths 0 to 1000). Both new test cases in unit-json_patch.cpp kept. single_include regenerated.

— posted by Claude Code on behalf of @nlohmann