Number Handling¶

This document describes how the library is handling numbers.

Background¶

This section briefly summarizes how the JSON specification describes how numbers should be handled.

JSON number syntax¶

JSON defines the syntax of numbers as follows:

The following railroad diagram from json.org visualizes the number syntax:

Number interoperability¶

On number interoperability, the following remarks are made:

Library implementation¶

This section describes how the above number specification is implemented by this library.

Number storage¶

In the default json type, numbers are stored as std::uint64_t, std::int64_t, and double, respectively. Thereby, std::uint64_t and std::int64_t are used only if they can store the number without loss of precision. If this is impossible (e.g., if the number is too large), the number is stored as double.

Number limits¶

• Any 64-bit signed or unsigned integer can be stored without loss of precision.
• Numbers exceeding the limits of double (i.e., numbers that after conversion via std::strtod are not satisfying std::isfinite such as 1E400) will throw exception json.exception.out_of_range.406 during parsing.
• Floating-point numbers are rounded to the next number representable as double. For instance 3.141592653589793238462643383279 is stored as 0x400921fb54442d18. This is the same behavior as the code double x = 3.141592653589793238462643383279;.

Zeros¶

The JSON number grammar allows for different ways to express zero, and this library will store zeros differently:

That is, -0 is stored as a signed integer, but the serialization does not reproduce the -.

Number serialization¶

• Integer numbers are serialized as is; that is, no scientific notation is used.
• Floating-point numbers are serialized as specified by the %g printf modifier with std::numeric_limits<double>::max_digits10 significant digits. The rationale is to use the shortest representation while still allow round-tripping.

std::printf("%.*g\n", std::numeric_limits<double>::max_digits10, double_value);

NaN handling¶

NaN (not-a-number) cannot be expressed with the number syntax described above and are in fact explicitly excluded:

That is, there is no way to parse a NaN value. However, NaN values can be stored in a JSON value by assignment.

This library serializes NaN values as null. This corresponds to the behavior of JavaScript's JSON.stringify function.

int main()
{
    double val = std::numeric_limits<double>::quiet_NaN();
    std::cout << "val=" << val << std::endl;
    json j = val;
    std::cout << "j=" << j.dump() << std::endl;
    val = j;
    std::cout << "val=" << val << std::endl;
}

val=nan
j=null
val=nan

Number comparison¶

Floating-point inside JSON values numbers are compared with json::number_float_t::operator== which is double::operator== by default.

template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
inline bool is_same(T a, T b, T epsilon = std::numeric_limits<T>::epsilon()) noexcept
{
    return std::abs(a - b) <= epsilon;
}

bool my_equal(const_reference lhs, const_reference rhs)
{
    const auto lhs_type lhs.type();
    const auto rhs_type rhs.type();
    if (lhs_type == rhs_type)
    {
        switch(lhs_type)
        {
            // self_defined case
            case value_t::number_float:
                return std::abs(lhs - rhs) <= std::numeric_limits<float>::epsilon();

            // other cases remain the same with the original
            ...
        }
    }
    ...
}

Number conversion¶

Just like the C++ language itself, the get family of functions allows conversions between unsigned and signed integers, and between integers and floating-point values to integers. This behavior may be surprising.

double d = 42.3;                                   // non-integer double value 42.3
json jd = d;                                       // stores double value 42.3
std::int64_t i = jd.template get<std::int64_t>();  // now i==42; no warning or error is produced

The rationale is twofold:

1. JSON does not define a number type or precision (see above).
2. C++ also allows to silently convert between number types.

// check if jd is really integer-valued
if (jd.is_number_integer())
{
    // if so, do the conversion and use i
    std::int64_t i = jd.template get<std::int64_t>();
    // ...
}
else
{
    // otherwise, take appropriate action
    // ...
}

Determine number types¶

As the example in Number conversion shows, there are different functions to determine the type of the stored number:

• is_number() returns true for any number type
• is_number_integer() returns true for signed and unsigned integers
• is_number_unsigned() returns true for unsigned integers only
• is_number_float() returns true for floating-point numbers
• type_name() returns "number" for any number type
• type() returns a different enumerator of value_t for all number types

Template number types¶

The number types can be changed with template parameters.

using json_ld = nlohmann::basic_json<std::map, std::vector, std::string, bool,
                                     std::int64_t, std::uint64_t, long double>;