Documentation of desired numeric Serialization Behaviour

[FelixBenning]

There are a ton of issues/bug reports when it comes to serializing numeric values (doubles), which implicitly define desired behaviour.

In an attempt to collect the desired behaviour in one place:

1. Round tripping double -> JSON -> double should incur no loss in precision (cf. Loss of precision when serializing <double> #360 (comment), Loss of precision when serializing <double> #360 (comment))
2. Except NaN, Inf are stored as is inside the C++ JSON structure, but are serialized to None (cf. nan number stored as null #388 (comment), Handle infinity and NaN cases #70 (comment)). This does break the first guarantee slightly.
3. (I assume that) the desired behaviour for String -> JSON -> String where the String is more precise than double is, that they are rounded to the closest double.
4. Desired Behaviour for numbers too large or small for doubles: json.exception.out_of_range.406 (cf. Doxygen Documentation of the error, Stack Overflow)

I think it should be documented somewhere how (De-)serialization of numeric values ought to happen, so that it is clear whether or not a specific behavior is a bug or working as intended.

I guess my Questions are: have I missed anything, is this correct?

[nlohmann]

This seems to be a good summary of issues that indeed need some better documentation.

[nlohmann]

@FelixBenning I added some documentation on number handling: https://json.nlohmann.me/features/types/number_handling/ - what do you think?

[FelixBenning]

The JSON number syntax was a bit confusing as I did not understand at first how that relates to nlohmann until I figured that it was just describing the JSON format in general. So I first tried to understand the railroad diagram as a parser until I realized that it was basically describing the number format, i.e.

• satisfies regex [0-9]+(\.[0-9]+)?([eE][-\+]?[0-9]+)?
• and leading 0 is only allowed if the dot follows right after

This is probably because I tend to look at pictures first and read text later - which might apply to other people as well.

Stuff like the RFC excerpts make a ton of sense to explain why nlohmann json works how it works, but do not really convey how nlohmann json works. In essence the why comes before the how here, which makes a ton of sense when you want to think about the implementation and what would make sense, but is not necessarily useful for the user.

So I would probably switch the "background" and the "library implementation" chapters around and maybe put a summary at the top (something like my 4 bullet points). This allows for a gradual:

• this is how it works (summary)
• this is how it works in detail (library implementation)
• and this is why it works the way it works (background)

learning curve.

[FelixBenning]

sorry forgot the tag @nlohmann