starred/json

0 Fork 0

mirror of https://github.com/nlohmann/json.git synced 2026-11-14 03:18:20 +00:00

Files

T

Niels Lohmann aaf63cbff6 docs: state that NaN ordering inside containers depends on the standard

When the element-wise comparison of arrays or objects reaches a NaN and
a number (or another NaN) before any other difference, the result
depends on the language standard. Before C++20 the pair counts as
equivalent and the following elements (or the sizes) decide, so
[1] <= [NaN] is true. Since C++20 the comparison is unordered and
<, <=, >, >= all yield false. Document this on operator<, <=, >, >=
and <=>.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-11-11 19:22:54 +01:00

3.9 KiB

Raw Blame History

nlohmann::basic_json::operator<=>

// since C++20
std::partial_ordering operator<=>(const_reference rhs) const noexcept;                   // (1)

template<typename ScalarType>
std::partial_ordering operator<=>(const ScalarType rhs) const noexcept(/* see below */); // (2)

3-way compares two JSON values producing a result of type std::partial_ordering according to the following rules:
- Two JSON values compare with a result of std::partial_ordering::unordered if either value is discarded.
- If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their respective operator<=>.
- Integer and floating-point numbers are 3-way compared by their exact values, without converting the integer to floating-point. For instance, 9007199254740993 compares greater than 9007199254740992.0.
- Otherwise, yields a result by comparing the type (see value_t).
3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way comparing both JSON values (see 1).

Template parameters

ScalarType: a scalar type according to std::is_scalar<ScalarType>::value

Parameters

rhs (in): second value to consider

Return value

the std::partial_ordering of the 3-way comparison of *this and rhs

Exception safety

No-throw guarantee: this function never throws exceptions.
No-throw guarantee if converting the scalar to a JSON value cannot throw, as for numbers, Booleans, and #!cpp nullptr; the function is #!cpp noexcept exactly in that case. Otherwise, it throws what the conversion throws, for example std::bad_alloc when converting a string, or out_of_range.410 for an enum value not mapped by NLOHMANN_JSON_SERIALIZE_ENUM_STRICT.

Complexity

Linear.

Notes

!!! note "Comparing NaN"

- `NaN` values are unordered within the domain of numbers.
  The following comparisons all yield `std::partial_ordering::unordered`:
    1. Comparing a `NaN` with itself.
    2. Comparing a `NaN` with another `NaN`.
    3. Comparing a `NaN` and any other number.
- For arrays and objects, the elements are compared in order. If the comparison reaches a `NaN` and a number (or
  another `NaN`) before any other difference, the result is `std::partial_ordering::unordered`. (Without C++20, the
  comparison operators `<`, `<=`, `>`, and `>=` use the comparison of the containers, which treats such a pair as
  equivalent; see [**operator<**](operator_lt.md).)

Examples

??? example "Example: (1) comparing JSON values"

The example demonstrates comparing several JSON values.

```cpp
--8<-- "examples/operator_spaceship__const_reference.c++20.cpp"
```

Output:

```json
--8<-- "examples/operator_spaceship__const_reference.c++20.output"
```

??? example "Example: (2) comparing JSON values and scalars"

The example demonstrates comparing several JSON values and scalars.

```cpp
--8<-- "examples/operator_spaceship__scalartype.c++20.cpp"
```

Output:

```json
--8<-- "examples/operator_spaceship__scalartype.c++20.output"
```

Version history

Added in version 3.11.0.
Added in version 3.11.0. Made conditionally #!cpp noexcept in version 3.13.0; before, a throwing conversion called std::terminate.

3.9 KiB Raw Blame History