Support a float precision in std::format: "{:.3}"

[maddanio]

Support a float precision in std::format: "{:.3}"

Reduced to the scope agreed in the review: std::format("{:.N}", j) only, with printf-exact rounding. There is no
dump() options struct and no stream wrapper. Streams can use os << std::format("{:.3}", j).

Behaviour

{:.N} writes floating-point numbers with N significant digits. The digits are exactly those that std::format
(and printf("%.*g")) writes for the number itself, including how ties are rounded:

value	std::format("{:.N}", json(v))	std::format("{:.N}", v)
π, N = 3	3.14	3.14
1.9999, N = 3	2.0	2
2.675, N = 3	2.67	2.67
12345.678, N = 3	1.23e+04	1.23e+04
0.1, N = 20	0.10000000000000000555	0.10000000000000000555

• A number that would otherwise read back as an integer gets a .0, as in dump().
• It combines with the existing specs: {:#.3}, {:2.3}, {:.>#1.2}.
• Integers are written exactly. NaN and infinity are still null.
• The docs say that the output no longer round-trips.
• Dynamic precision ({:.{}}) and . without digits are still rejected.
• The precision is capped at 1000, which covers every significant digit of a double (at most 767).

Implementation

Three commits:

1. Serializer: a trailing float_precision_ constructor argument. A negative value, the default, keeps today's
   output.
   • With a precision, every floating-point type takes the snprintf("%.*g") path that non-IEEE types such as a
     wider long double already use. It's the same function with the same locale handling; only the digit count
     changes from max_digits10 to N. The existing code was moved into a helper that both call, and the
     long double default output is unchanged.
   • One addition on this path only: trailing zeros of the fraction are removed, as %g requires. macOS's printf
     keeps them on exact ties in exponent notation: %.3g of 5405000 gives 5.40e+06, where std::format gives
     5.4e+06.
   • The serializer is in detail, so this is not public API.
2. std::format: parse .N in std::formatter<basic_json> and pass it to the serializer. Includes docs and the
   example, whose output is checked.
3. Amalgamate: single_include regenerated in a commit of its own, so that the first two diffs contain only the
   real changes.

Default path: unchanged output, benchmark

dump() without a precision, -O2, M-series Mac:

• Output: byte-for-byte identical to develop on 1M random doubles (18.7 MB), with both compilers.
• 1M random doubles, median of 31 runs:
  • Apple clang 21: develop 67.1–67.7 ms, this branch 67.3–67.7 ms.
  • GCC 15: develop 65.0–65.2 ms, this branch 64.5–64.7 ms.
• canada.json, median of 200 runs, Apple clang: develop 7043–7105 µs, this branch 7034–7124 µs.

The precision path is marked JSON_HEDLEY_NEVER_INLINE. Without it, the default path was about 0.7% slower, and a
control build without the precision check showed that the check caused it. The likely reason is the path's 1 KB stack
buffer: inlined, it enlarges the stack frame for every number. With the attribute, the difference is within noise.

Tests

• unit-float-precision.cpp (new):
  • rounding, the carry, ties, notation;
  • precision 0 and large precisions;
  • integers, NaN/inf, nested and pretty-printed values;
  • float and long double;
  • 100,000 random values checked against std::setprecision.
• unit-std-format.cpp:
  • the spec, combinations, and rejected forms;
  • 100,000 random values where std::format("{:.N}", json(v)) must equal std::format("{:.N}", v) (plus .0).
    Checked against both libc++ and libstdc++.
• unit-locale-cpp.cpp: the precision path under de_DE, where the decimal point is ,.
• Test runs (macOS):
  • The full suite with Apple clang (131 tests).
  • The new and changed tests with GCC 15, including the ci_test_gcc warning set that failed in the previous CI
    run (-Wformat-truncation=2 and more).

🤖 Generated with Claude Code

[gregmarr]

Since the dump_options class is already in serializer.hpp, would it make sense to update serializer to use it, rather than converting to the individual parameters?

[maddanio]

Thought so too, will look into it

[maddanio]

Is it public api? Do i have to keep the arg variant?

[gregmarr]

I don't think so, because it's in the detail namespace. @nlohmann can you confirm?

[nlohmann]

I am not a fan of the options struct, and we excluded it from the scope in #1170 (comment). The reason is that we have so many issues regarding dump options that I'm afraid of adding options we may want to revisit later which would mean breaking changes.

[nlohmann]

@maddanio Fair enough, you deserve a clear answer, so here it is.

Precision: yes, through std::format only. I'm not the person who needs it, but #1170 has been open since 2018 and people keep asking for it. std::format("{:.3}", j) gives a meaning to a spec that is rejected today, and that meaning comes from std::format itself. There are no new names or types, and nothing to design. In a stream, os << std::format("{:.3}", j) does the job.

dump_options: not in this PR. This isn't about precision. It's about what a public struct commits us to:

• Every option costs testing and maintenance. An option gets tested alone and in combination with the others (indent × ensure_ascii × error_handler × precision × …), and it gets documented and supported for as long as the library exists. That cost doesn't depend on how small the patch is.
• Public API is final. Once dump(const dump_options&) ships, we can't remove it, rename a member, change a member's type or meaning, or change a default without breaking someone's code. @gregmarr, to your question: appending members is the only change that's safe. Everything that's already in the struct is frozen.
• So the struct has to be right on the first try, and we don't know yet what "right" is. Copying today's four parameters 1:1 would freeze their limits a second time: indent uses -1 to mean "compact", indent_char is a single char, and ensure_ascii is a bool even though people have asked for other escaping behaviour (dump(): Non-conforming with JSON-spec escape of strings? #4088, How to avoid escaping for an already escaped string in .dump() #2870). There are also requests the struct would have to fit later, like arrays on one line (Please add a Pretty-Print option for arrays to stay always in one line #229) and raw/lossless numbers (Idea: lossless number round-tripping (raw / arbitrary-precision number mode) #5296). A float_precision int with a negative sentinel may not be how we want to express number formatting once Idea: lossless number round-tripping (raw / arbitrary-precision number mode) #5296 is on the table. I'd rather design the struct once, from all of those requests, than let the first option that needs it decide its shape.

Your arguments for the struct are good ones, and I still think we'll get one eventually. But that needs its own issue and its own design discussion, not a fourth commit on a precision PR.

The stream wrapper: also not in this PR. I have to take back what I asked for in #1170. The wrapper has the same problem as the struct, just smaller. It's a public name we can never change, and it only covers one option. Once we have an options struct, streams will want one wrapper that takes all the options, and with_float_precision would stay behind as a duplicate we have to keep forever. It also holds a reference to j, so auto w = with_float_precision(make_json(), 3); os << w; dangles.

The cost is that C++11–17 and fmt users don't get precision until the options design exists. The fmt::formatter recipe can only call the public dump(), so it has no way to pass a precision. I think that's the right order: the first non-std::format way to set a precision should come from that design.

@gregmarr On your second question: serializer is in detail, so its signature isn't public API. Without a public struct, though, there's nothing to switch it to, so the point goes away.

Rounding ties: because {:.N} is std::format syntax, people will compare std::format("{:.3}", j) with std::format("{:.3}", 2.675) and expect the same digits. Once this ships, we can't change which way ties round, so it has to be right on the first try as well. That makes me lean toward the printf-exact tie fallback you already tested.

Next steps: please reduce this PR to commits 1 and 2 (serializer + std::format), and use the printf-exact tie rounding.

[gregmarr]

Thanks for explaining all that @nlohmann, that all makes sense.

[maddanio]

ok, but std format is not really the standard way of dumping a huge file. so can I put the other two to PRs? If its onloy format I mean, sure, grad I could help, but still did not address my use case. Also for the tie: that means using snprintf or to_char, because grisu simply cannot do it.

[maddanio]

So this with format only and to_char/snprintf and then I would try the stream wrapper again with an appropriately open precision config

[maddanio]

Ah you want a dangling safe wrapper with config struct? That sounds klunky, but the whole wrapper is. Manipulators would be better. But there you a static xalloc call.

[maddanio]

changed: only std::format supported and uses snprintf as was already the case for long double