Speed up dump(), and keep it from overflowing the stack

[nlohmann]

What & why

dump() had two hot spots that mirror exactly what #5283 fixed on the parse side, so this PR reuses that PR's SWAR/UTF-8 primitives (detail/input/string_scan.hpp) to fix the serializer. Output is byte-for-byte unchanged on every input; only the path taken to produce it is faster.

Note on the base branch: this is stacked on claude/parser-performance-research-4hkdf8 (#5283), because it reuses that PR's string_scan.hpp scanner and validator. The diff here is only the serializer + tests; once #5283 lands on develop, this can be retargeted to develop unchanged.

The changes (each independent and reversible)

1. SWAR bulk string escaping (ensure_ascii == false) — dump_escaped() ran the UTF-8 DFA over every byte of every string and key, even for ordinary text with nothing to escape (the serializer twin of the parser's per-character get()). At a character boundary it now bulk-copies the longest run needing no escaping via string_bulk_run() — the same scanner + UTF-8 bulk validator the lexer's contiguous path uses — and drops to the byte-at-a-time DFA only for the first byte that needs individual handling (a quote, backslash, control char, or ill-formed/truncated UTF-8). For ensure_ascii == false, string_bulk_run()'s stop set is an exact match for the bytes dump_escaped copies verbatim, so escaping and error handling (including strict-mode error 316 position and message) are identical. Picks up JSON_USE_SIMDUTF for free.

2. Internal write buffer (devirtualization) — every structural character ({, ", ,, …) previously went straight to the output adapter through a virtual call. All writes now route through put_char/put_chars into a 1 KiB buffer flushed in bulk; the public dump() flushes once the top-level value is serialized (the recursive worker is split out as dump_internal). Runs larger than the buffer are written straight through, so large payloads are not copied twice. This is the dominant cost for object/array-heavy values.

3. ensure_ascii == true fast path — added find_ascii_copyable_run() (a SWAR scan stopping at ", \, < 0x20, 0x7F, and >= 0x80) so runs of printable ASCII are bulk-copied even when non-ASCII must be \u-escaped. 0x7F/DEL is a deliberate stop (it is escaped under ensure_ascii), which is why find_string_special() could not be reused directly here.

4. Bounded descent, so dump() cannot overflow the stack (Stack overflow in copy constructor and dump() on deeply nested json (destructor was fixed in #1436) #5387) — serializing a container serialized its elements, so dump() descended into one call per nesting level and a value nested deeply enough terminated the process with SIGSEGV, no exception to catch. Parsing such a value works (the parser is iterative) and so does destroying one (Prevent stackoverflow caused by recursive deconstruction #1436); serializing never got the same treatment. The descent is now bounded: the first 128 levels are written by exactly the code that always wrote them, and only below that does a new dump_iteratively write out what is left, keeping the containers it has entered on an explicit stack.

   Writing every value that way instead — the obvious fix — measured 2% to 20% slower, 20% on object-heavy documents, which would have undone much of what this PR is for. Keeping the descent for everything that can afford it costs one comparison per container: between -1.4% and +1.2% across compact and pretty output of number, integer, string, object-heavy, wide-object and deeply nested documents.

   Both writers emit the separator in front of every element but the first, rather than after every element but the last; that puts exactly one between each pair and none at the end.

5. ensure_ascii folded into the escaper — dump_escaped() took it as a runtime flag and tested it inside the loop, once per character run, although it cannot change while a string is written. It is now a template parameter dispatched once per string, which folds the choice of scanner and lets each of the two be inlined into a loop of its own. This is the hottest loop in the serializer — it runs over every string and every object key.

6. Binary bytes no longer go through dump_integer — a byte is always in [0, 255], so it needs neither digit counting nor 64-bit arithmetic; dump_byte writes the at most three digits straight into the write buffer. Any byte type that is not a plain unsigned byte is still left to dump_integer, whose representation of it may differ.

   Gains from 5 and 6 (medians of 9 interleaved runs, clang -O3, against the commit before them):

   workload
   binary values	-33.8%
   dense CJK, ensure_ascii=true	-20.6%
   small value dumped in a loop	-21.4%
   deeply nested, pretty	-17.9%
   key-heavy objects	-17.8%
   dense CJK, ensure_ascii=false	-11.8%
   object-heavy, compact / pretty	-9.3% / -9.5%
   wide objects	-2.3%
   integer and float arrays	unchanged
   arrays of plain ASCII strings	+3.5% to +4.2%

   The last row is the one shape that loses, consistently across two independent benchmarks. It is a small cost against the rest, but it is a real one.

   Tried and dropped: leaving the write and string buffers uninitialized instead of zeroing 1.5 KB per dump() call. Worth -30% on small values, but two nearly identical string workloads moved 18% apart in opposite directions, so the measurement did not support the change — and it would have traded away safety margin that cannot be checked here (MemorySanitizer is unavailable on arm64 macOS).

Measured gains

json::dump(), C++17, g++ 13 -O3, vs the pre-change serializer (representative synthetic data):

dataset	speedup
long ASCII strings, ensure_ascii=false	4.2×
long ASCII strings, ensure_ascii=true	4.1×
twitter-like objects	2.7×
pretty-printed objects	2.4×
dense CJK	1.8× (further headroom with JSON_USE_SIMDUTF)
integer arrays	1.1×

Verification

• Differential (used for items 4-6): every check below is byte-for-byte identical against the pre-change serializer, and now also covers every one of the 256 byte values, alone and together, in both binary layouts.
• Differential for the bounded descent: ~980k lines of output compared against the pre-change serializer and found identical — 700 randomized values plus curated shapes, each dumped in every combination of six indents (including one wider than the write buffer), both indent characters, both ensure_ascii settings and all three error handlers; plus every nesting depth from 1 to 300 in array, object and mixed shapes at three indent settings, so the depth at which the two writers hand over is covered from every side. New tests cover a 100,000-deep value (which crashes on the base), the depths around the bound, pretty-printing across it, and empty containers reached below it.
• Differential: dump output is byte-for-byte identical to the pre-change implementation across ~20k randomized byte strings plus curated edge cases (all escapes, control chars, 0x7F, valid multibyte, surrogates, overlong, truncated sequences), for compact/pretty and object/array output, both ensure_ascii settings, and all three error handlers, in C++11/17/20 at -O2/-O3.
• New serialization tests cover the write-buffer flush boundaries (>1 KiB strings, 2000-element arrays, 1100-deep nesting), escape and 0x7F handling, multibyte under both settings, and invalid-UTF-8 handling.
• Warning-clean under clang -Weverything and the gcc pedantic flag set; clang-tidy clean on the changed headers; make check-amalgamation clean.

How other libraries handle this

Worth knowing where this sits, because the trade-off taken here is deliberately not the common one.

Most libraries reject deeply nested input rather than support it — a hard depth limit at parse time, which then protects everything downstream:

library	limit
Boost.JSON	parse_options::max_depth = 32
serde_json	128, then RecursionLimitExceeded
Jackson	maxNestingDepth 1000 (500 in 3.0)
simdjson	1024, refuses to parse deeper
.NET System.Text.Json	65

Jackson's limit exists because of CVE-2025-52999, and CVE-2026-29062 covers a parser that bypassed it; PostgreSQL patched its OAuth JSON parser the same way. Only a few libraries are iterative throughout instead: yyjson advertises "unlimited JSON nesting levels" as a headline feature, and miniserde gives its value type a non-recursive Drop. A third approach is to grow the stack on demand, as serde_stacker does.

This library sits in the worst spot of the three. Its parser is iterative, so it accepts input nested arbitrarily deeply — and then hands it to operations that cannot cope. lovasoa/bad_json_parsers, which measures exactly this, buckets it under "unlimited → segfault". A library with a parse limit never builds such a value in the first place.

The closest C++ peer has the same split and has fixed none of it. RapidJSON's kParseIterativeFlag makes only parsing iterative, and is opt-in because the recursive parser is faster; its destructor is still recursive (#2217, open, asking for exactly what #1436 did here in 2019), CopyFrom still overflows on deep values, and Value::Accept() — its serializer — still recurses.

Two things that supports about the approach taken here: RapidJSON keeps recursion as the default because it is faster, which matches the measurement that writing every value iteratively costs up to 20%; and a bound of 128 sits in the same range as everyone else's hard limits — except that nothing is rejected at it, so this library stays strictly more permissive than all of them while no longer crashing.

---

• The changes are described in detail, both the what and why.
• If applicable, an existing issue is referenced. (none; follow-up to Speed up parsing of contiguous input: numbers, strings, and UTF-8 (with optional simdutf) #5283)
• The code coverage remained at 100%. A test case for every new line of code.
• If applicable, the documentation is updated. (no public API or option changes)
• The source code is amalgamated by running make amalgamate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XAYM1qhSA2FDaDcGfPW3fG

---

Generated by Claude Code

[wilkolbrzym-coder]

Quick review notes

• Critical bug in binary pretty‑print: indent_string.resize(indent_string.size() * 2, ' ') doubles the string every time a binary value is serialized, causing exponential memory growth. Should be a conditional resize to new_indent instead.

• Missing check: the fast path uses string_bulk_run, but its implementation isn’t shown – please verify it correctly stops at incomplete/ill‑formed UTF‑8 to keep error handling (replace/ignore) intact.

• Nit: replace magic 1024 buffer size with a named constant for readability.

Otherwise, the SWAR scanner and buffering logic look solid. 👍

[nlohmann]

Thanks for your feedback!

1. Real, but pre-existing: already fixed by Fix indentation overflow and correctness bug #5186
2. Not a bug: verified correct in string_scan.hpp
3. Yes, style nit.

[gregmarr]

not guaranteed to be big enough (handled by #5186).

[nlohmann]

Right, and it turned out to be worth chasing: indent_string is gone as of a1e9147.

put_indent() now memsets the indentation straight into the write buffer, filling and flushing it as needed, so there is no auxiliary string to size, grow, or keep in sync with the deepest nesting level reached. That removes both halves of #5186 structurally rather than patching the growth rule — the doubling that isn't enough when indent_step more than doubles the string, and the ' ' literal in the resize instead of indent_char.

Both were reproducible against develop:

• json{{"a", 1}}.dump(2000) — indent_string starts at 512, doubles once to 1024, then 2000 bytes are read from it. Right length, garbage content: a heap over-read.
• json{{"a", 1}}.dump(600, '\t') — the part past 512 comes back as spaces, not tabs.

Both now pass, and there are tests for them (plus one for nesting whose accumulated indentation spans several buffer-fulls). next_indent() keeps #5186's assertion that the unsigned indentation accumulation hasn't wrapped on deep nesting, since that one is independent of how the characters get written.

@nlohmann — this does mean #5186 will conflict here and its reserve_indent() has nothing left to reserve. Worth deciding which lands first, especially with an advisory pointing at it.

(Written by Claude Code.)

[gregmarr]

There are multiple separate things being handled by this function.

1. Write the characters of a string literal.
2. Write a number of indent characters.
3. Write the first len characters from a std::array<char, N>.
4. Write an arbitrary number of characters from an arbitrary position in a string_t.

I'm not sure that each of these should be the same function.

Number 1 is asking for the number to get out of sync with the length of the string literal. It could be something like this:

template<int N> void put_literal(const char (&str)[N])
{
  const int length = N - 1;
  if (JSON_HEDLEY_UNLIKELY(write_buffer_pos + length >= write_buffer.size()))
  {
    flush();
  }
  std::memcpy(write_buffer.data() + write_buffer_pos, str, length);
  write_buffer_pos += length;
}

maybe with some enable_if to keep N under 1024 so you don't need to worry about it overflowing.

Number 2 could be:

void put_indent(unsigned int indent)
{
        if (JSON_HEDLEY_UNLIKELY(write_buffer_pos + indent > write_buffer.size()))
        {
            flush();
        }
        if (JSON_HEDLEY_UNLIKELY(indent > write_buffer.size()))
        {
          // the buffer is clear, fill it with the indent character
          std::memset(write_buffer.data(), indent_char, write_buffer.size());
          // keep writing it out until all the indent is processed.
          while (JSON_HEDLEY_UNLIKELY(indent > write_buffer.size()))
          {
            flush();
            indent -= write_buffer.size();
          }
          // set the write position to cover the rest of the indent
          write_buffer_pos = indent;

          return;
        }

        std::memset(write_buffer.data() + write_buffer_pos, indent_char, indent);
        write_buffer_pos += indent;
  }

which also eliminates the need for indent_string and resizing it.

Number 3 and 4 could be safer than just a char * and a count, not sure if they could easily share a "safer" implementation though.

[nlohmann]

Agreed — split into separate entry points in a1e9147, close to what you sketched.

1. String literals → put_literal(), taking the literal by reference and deducing the length from the array bound, as you had it. All 27 call sites converted. For what it's worth I checked every hand-written count before replacing it and none of them was actually wrong today, but the class of bug is gone.

One deviation: instead of an enable_if to bound N, the length is checked against the buffer with a static_assert, which lets the oversized-run branch disappear entirely rather than becoming unreachable — this repo wants 100% line coverage, so an uncoverable branch is its own small problem.

template<std::size_t N>
void put_literal(const char (&s)[N])
{
    static_assert(N >= 2, "put_literal expects a non-empty string literal");
    static_assert(N - 1 < write_buffer_size, "string literal must fit into the write buffer");
    ...
}

2. Indentation → put_indent(), and this removes indent_string and the resizing exactly as you predicted. Details in the other thread, since it also settles #5186.

Your sketch needs one adjustment though: in the wider-than-the-buffer loop, write_buffer_pos is already 0 from the first flush() and never set back to write_buffer.size(), so each flush() inside the while writes zero characters — the buffer gets memset but nothing comes out, and the indentation ends up truncated. I used a fill-and-flush loop instead, which also collapses the two cases into one:

void put_indent(unsigned int indent)
{
    while (indent > 0)
    {
        if (JSON_HEDLEY_UNLIKELY(write_buffer_pos == write_buffer.size()))
        {
            flush();
        }

        const std::size_t chunk = (std::min)(static_cast<std::size_t>(indent),
                                             write_buffer.size() - write_buffer_pos);
        std::memset(write_buffer.data() + write_buffer_pos, indent_char, chunk);
        write_buffer_pos += chunk;
        indent -= static_cast<unsigned int>(chunk);
    }
}

3. std::array + length → put_buffer(const std::array<char, N>&, std::size_t), so the length is checked against the buffer's own bound instead of travelling next to a bare pointer. Covers the string_buffer and number_buffer writes.

4. Arbitrary range of a string_t → left on put_chars(). Together with to_chars()'s output those are the only two callers now, and both are genuinely a pointer into the middle of something plus a length; I didn't find a safer shape that didn't just move the arithmetic. Open to ideas.

(Written by Claude Code.)

[gregmarr]

write_buffer_pos is already 0 from the first flush() and never set back to write_buffer.size(), so each flush() inside the while writes zero characters

Yep, needed a write_buffer_pos = write_buffer.size(); before the flush().

I used a fill-and-flush loop instead, which also collapses the two cases into one:

I was trying to avoid the memset() on every iteration. If you have an indent of 4x the buffer size, you'll fill the whole buffer 4 times with the indent character, which is essentially a no-op on 3 of them because you know the state of the buffer.

[nlohmann]

Both fair — fixed in b4fdf76.

You're right that re-filling the buffer is wasted work: flushing doesn't disturb what the buffer holds, so it only needs writing once. It now fills the room that's left, and if anything remains, flushes, fills the buffer once, and re-flushes that same content:

void put_indent(unsigned int indent)
{
    // closing braces at the outermost level ask for no indentation at all
    if (indent == 0)
    {
        return;
    }

    const std::size_t capacity = write_buffer.size();

    const std::size_t head = (std::min)(static_cast<std::size_t>(indent), capacity - write_buffer_pos);
    std::memset(write_buffer.data() + write_buffer_pos, indent_char, head);
    write_buffer_pos += head;
    indent -= static_cast<unsigned int>(head);

    if (JSON_HEDLEY_LIKELY(indent == 0))
    {
        return;
    }

    flush();
    std::memset(write_buffer.data(), indent_char, capacity);

    while (indent >= capacity)
    {
        write_buffer_pos = capacity;
        flush();
        indent -= static_cast<unsigned int>(capacity);
    }

    // the buffer still holds indentation characters throughout, so the tail
    // only has to be claimed, not written again
    write_buffer_pos = indent;
}

Counting memset calls and bytes inside put_indent over a dump():

indent	before	after
4	1 call / 4 B	1 call / 4 B
2000	2 calls / 2000 B	2 calls / 2046 B
100000	98 calls / 100000 B	2 calls / 2046 B

Constant instead of proportional to the width, and ordinary indents are untouched. The indent == 0 early return is worth having on its own — every outermost closing brace asks for a zero-width indent, and without it the common path paid for a zero-length memset.

Tests extended to cover several whole buffer-fulls and an exact multiple of the buffer size.

(Written by Claude Code.)

[gregmarr]

4. Arbitrary range of a string_t → left on put_chars(). Together with to_chars()'s output those are the only two callers now, and both are genuinely a pointer into the middle of something plus a length; I didn't find a safer shape that didn't just move the arithmetic. Open to ideas.

This at least puts all the arithmetic inside the function.

template<typename StringOrArray>
void put_string(StringOrArray const &str, std::size_t start, std::size_t end)
{
  JSON_ASSERT(start < str.size());
  JSON_ASSERT(end< str.size());
  JSON_ASSERT(start < end);
  const std::size_t length = end - start;
  const char *s = str.data();
...
}

[nlohmann]

That does, and it is the better shape — added as put_string() in 5567a0e.

Two adjustments to the assertions. end is exclusive, so end <= str.size() rather than <: a run reaching the end of the string is the normal case in dump_escaped, and < would fire on it. And start < end rules out the empty range, which is harmless to write, so I made that <= too and dropped the separate start check as implied:

template<typename StringType>
void put_string(const StringType& str, std::size_t start, std::size_t end)
{
    JSON_ASSERT(start <= end);
    JSON_ASSERT(end <= str.size());
    put_chars(str.data() + start, end - start);
}

With this and the dump_float fix from the other thread, put_chars() is down to two callers, both of them put_string()/put_buffer() — so nothing outside the buffer helpers passes a bare pointer and a count any more, which was your original point.

(Written by Claude Code.)

[gregmarr]

This comment block got detached from put_chars.

[nlohmann]

Good catch — entirely my doing. I inserted put_indent/put_literal/put_buffer in front of put_chars and left its comment sitting on top of the first new function, so put_indent ended up with two doc blocks and put_chars with none. Reattached in 5567a0e.

(Written by Claude Code.)

[gregmarr]

update to put_buffer?

[nlohmann]

Yes — missed that one. begin is number_buffer.data(), so it is the same fixed-size-buffer case as the others; it is put_buffer(number_buffer, ...) as of 5567a0e.

That was the last one: put_chars() now has no callers outside put_string()/put_buffer().

(Written by Claude Code.)

[gregmarr]

4. Arbitrary range of a string_t → left on put_chars(). Together with to_chars()'s output those are the only two callers now, and both are genuinely a pointer into the middle of something plus a length; I didn't find a safer shape that didn't just move the arithmetic. Open to ideas.

This at least puts all the arithmetic inside the function.

template<typename StringOrArray>
void put_string(StringOrArray const &str, std::size_t start, std::size_t end)
{
  JSON_ASSERT(start < str.size());
  JSON_ASSERT(end< str.size());
  JSON_ASSERT(start < end);
  const std::size_t length = end - start;
  const char *s = str.data();
...
}

[gregmarr]

I still like only computing the length once so you don't forget the - 1:

  const int length = N - 1;

[nlohmann]

Fair, and it reads better. Done in 5567a0e:

static_assert(N >= 2, "put_literal expects a non-empty string literal");
// the array bound counts the terminating NUL, which is not written
constexpr std::size_t length = N - 1;
static_assert(length < write_buffer_size, "string literal must fit into the write buffer");

constexpr rather than const so the static_assert can still use it, and std::size_t to match what it is compared against.

(Written by Claude Code.)

[gregmarr]

Not a change here, but the "subtype" about 30 lines later doesn't have a space after the colon.

[nlohmann]

Checked this one rather than trusting the read — I think the two you are comparing are in different branches. Line 294 is the pretty-print path ("subtype": with the space); the one about 30 lines later, at 322, is the compact path (],"subtype":), where nothing has spaces.

Actual output, and it is byte-identical to develop:

--- compact ---
{"b":{"bytes":[1,2,3],"subtype":42},"n":{"bytes":[1,2,3],"subtype":null}}
--- pretty ---
{
  "b": {
    "bytes": [1, 2, 3],
    "subtype": 42
  },
  ...
}

So both modes are internally consistent and neither changed here. No fix — but say the word if you were pointing at something else.

(Written by Claude Code.)

[gregmarr]

I couldn't tell from the restricted diff that one was pretty and one wasn't (one having newlines and one not should have given me a clue but didn't), so this difference makes sense.

[gregmarr]

Should the indent be size_t then?

[nlohmann]

Yes — changed in 5567a0e. It is a size, it is compared and combined with buffer sizes throughout, and put_indent() was casting to std::size_t and back on every call. dump(), dump_internal(), next_indent() and put_indent() all carry std::size_t now, and the casts are gone.

I kept next_indent()'s assertion: on a 64-bit size_t you would need an implausible nesting depth to wrap it, but it is still reachable where size_t is 32 bits, which is the same place the original unsigned int overflow was reachable.

(Written by Claude Code.)

[gregmarr]

Looks like I didn't write out part of what I was thinking. I was thinking that this would replace put_chars. That way there would not be a function that took a const char * and a length. Then put_buffer is just put_string(buffer, 0, length); That's why I had

  const std::size_t length = end - start;
  const char *s = str.data();
...

as the rest of the function would be the current body of put_chars().

[gregmarr]

Rather than bailing out here to what is basically a copy of this function that can get out of sync, can you have the stack here and either recurse or push onto the stack based on the current depth? I haven't analyzed in depth enough to know if that would be possible.

[gregmarr]

Would it be better to do write_buffer_pos++ along with each out++ and avoid the pointer math here?

[gregmarr]

Inserted the new function between the comment block and the old function again.

[gregmarr]

Is this variable even needed? Just use write_buffer_pos directly?