Normalize -0.0 in number hashes and test range ends

operator== compares numbers exactly since #5459, so equal numbers
share one value and convert to the same number_float_t. Update the
comment accordingly, map -0.0 to 0.0 before hashing (std::hash need
not do that), and test -0.0 and the ends of the integer ranges. Show
hash(0.0) in the docs example and note the change in the version
history.

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

docs/mkdocs/docs/api/basic_json/std_hash.md

@@ -7,8 +7,9 @@ namespace std {
 ```
 
 Return a hash value for a JSON object. The hash function tries to rely on `std::hash` where possible. Furthermore, the
-type of the JSON value is taken into account to have different hash values for `#!json null`, `#!cpp 0`, `#!cpp 0U`, and
-`#!cpp false`, etc.
+type of the JSON value is taken into account, so `#!json null`, `#!cpp false`, and numbers all hash differently from
+each other. Numbers that compare equal under [`operator==`](operator_eq.md) always hash equally, regardless of
+whether they are stored as `#!cpp 0`, `#!cpp 0U`, or `#!cpp 0.0`.
 
 ## Examples
 
@@ -36,3 +37,5 @@ type of the JSON value is taken into account to have different hash values for `
 
 - Added in version 1.0.0.
 - Extended for arbitrary basic_json types in version 3.10.5.
+- Numbers that compare equal hash equally since version 3.13.0; before, `#!cpp 0`, `#!cpp 0U`, and `#!cpp 0.0` had
+  different hash values.

docs/mkdocs/docs/examples/std_hash.cpp

@@ -11,6 +11,7 @@ int main()
               << "hash(false) = " << std::hash<json> {}(json(false)) << '\n'
               << "hash(0) = " << std::hash<json> {}(json(0)) << '\n'
               << "hash(0U) = " << std::hash<json> {}(json(0U)) << '\n'
+              << "hash(0.0) = " << std::hash<json> {}(json(0.0)) << '\n'
               << "hash(\"\") = " << std::hash<json> {}(json("")) << '\n'
               << "hash({}) = " << std::hash<json> {}(json::object()) << '\n'
               << "hash([]) = " << std::hash<json> {}(json::array()) << '\n'

docs/mkdocs/docs/examples/std_hash.output

@@ -1,8 +1,9 @@
 hash(null) = 2654435769
 hash(false) = 2654436030
-hash(0) = 2654436095
-hash(0U) = 2654436156
-hash("") = 6142509191626859748
+hash(0) = 2654436221
+hash(0U) = 2654436221
+hash(0.0) = 2654436221
+hash("") = 11160318156688833227
 hash({}) = 2654435832
 hash([]) = 2654435899
-hash({"hello": "world"}) = 4469488738203676328
+hash({"hello": "world"}) = 3701319991624763853

include/nlohmann/detail/hash.hpp

@@ -35,8 +35,10 @@ std::size_t hash_iteratively(const BasicJsonType& j);
 @brief hash a JSON value
 
 The hash function tries to rely on std::hash where possible. Furthermore, the
-type of the JSON value is taken into account to have different hash values for
-null, 0, 0U, and false, etc.
+type of the JSON value is taken into account, so null, false, and numbers all
+hash differently from each other, but any two numbers that compare equal
+under operator== hash equally regardless of which of number_integer,
+number_unsigned, or number_float actually holds the value.
 
 Hashing an array or an object hashes its elements, which used to call this
 function again once per nesting level, so a value nested deeply enough
@@ -55,8 +57,6 @@ template<typename BasicJsonType>
 std::size_t hash(const BasicJsonType& j, const std::size_t depth = 0)
 {
     using string_t = typename BasicJsonType::string_t;
-    using number_integer_t = typename BasicJsonType::number_integer_t;
-    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
     using number_float_t = typename BasicJsonType::number_float_t;
 
     const auto type = static_cast<std::size_t>(j.type());
@@ -113,21 +113,20 @@ std::size_t hash(const BasicJsonType& j, const std::size_t depth = 0)
         }
 
         case BasicJsonType::value_t::number_integer:
-        {
-            const auto h = std::hash<number_integer_t> {}(j.template get<number_integer_t>());
-            return combine(type, h);
-        }
-
         case BasicJsonType::value_t::number_unsigned:
-        {
-            const auto h = std::hash<number_unsigned_t> {}(j.template get<number_unsigned_t>());
-            return combine(type, h);
-        }
-
         case BasicJsonType::value_t::number_float:
         {
-            const auto h = std::hash<number_float_t> {}(j.template get<number_float_t>());
-            return combine(type, h);
+            // operator== compares numbers by their mathematical value across
+            // number_integer, number_unsigned, and number_float, so equal
+            // numbers of different internal types (0, 0U, 0.0) must hash the
+            // same. Two equal numbers have the same value, which converts to
+            // the same number_float_t, so all numbers share one type tag and
+            // hash that converted value. Adding zero turns -0.0 (equal to 0)
+            // into 0.0, as std::hash need not map both to the same hash.
+            const auto number_type = static_cast<std::size_t>(BasicJsonType::value_t::number_float);
+            const auto value = j.template get<number_float_t>() + static_cast<number_float_t>(0);
+            const auto h = std::hash<number_float_t> {}(value);
+            return combine(number_type, h);
         }
 
         case BasicJsonType::value_t::binary:

single_include/nlohmann/json.hpp

@@ -7636,8 +7636,10 @@ std::size_t hash_iteratively(const BasicJsonType& j);
 @brief hash a JSON value
 
 The hash function tries to rely on std::hash where possible. Furthermore, the
-type of the JSON value is taken into account to have different hash values for
-null, 0, 0U, and false, etc.
+type of the JSON value is taken into account, so null, false, and numbers all
+hash differently from each other, but any two numbers that compare equal
+under operator== hash equally regardless of which of number_integer,
+number_unsigned, or number_float actually holds the value.
 
 Hashing an array or an object hashes its elements, which used to call this
 function again once per nesting level, so a value nested deeply enough
@@ -7656,8 +7658,6 @@ template<typename BasicJsonType>
 std::size_t hash(const BasicJsonType& j, const std::size_t depth = 0)
 {
     using string_t = typename BasicJsonType::string_t;
-    using number_integer_t = typename BasicJsonType::number_integer_t;
-    using number_unsigned_t = typename BasicJsonType::number_unsigned_t;
     using number_float_t = typename BasicJsonType::number_float_t;
 
     const auto type = static_cast<std::size_t>(j.type());
@@ -7714,21 +7714,20 @@ std::size_t hash(const BasicJsonType& j, const std::size_t depth = 0)
         }
 
         case BasicJsonType::value_t::number_integer:
-        {
-            const auto h = std::hash<number_integer_t> {}(j.template get<number_integer_t>());
-            return combine(type, h);
-        }
-
         case BasicJsonType::value_t::number_unsigned:
-        {
-            const auto h = std::hash<number_unsigned_t> {}(j.template get<number_unsigned_t>());
-            return combine(type, h);
-        }
-
         case BasicJsonType::value_t::number_float:
         {
-            const auto h = std::hash<number_float_t> {}(j.template get<number_float_t>());
-            return combine(type, h);
+            // operator== compares numbers by their mathematical value across
+            // number_integer, number_unsigned, and number_float, so equal
+            // numbers of different internal types (0, 0U, 0.0) must hash the
+            // same. Two equal numbers have the same value, which converts to
+            // the same number_float_t, so all numbers share one type tag and
+            // hash that converted value. Adding zero turns -0.0 (equal to 0)
+            // into 0.0, as std::hash need not map both to the same hash.
+            const auto number_type = static_cast<std::size_t>(BasicJsonType::value_t::number_float);
+            const auto value = j.template get<number_float_t>() + static_cast<number_float_t>(0);
+            const auto h = std::hash<number_float_t> {}(value);
+            return combine(number_type, h);
         }
 
         case BasicJsonType::value_t::binary:

tests/src/unit-hash.cpp

@@ -12,8 +12,10 @@
 using json = nlohmann::json;
 using ordered_json = nlohmann::ordered_json;
 
+#include <limits>
 #include <set>
 #include <string>
+#include <unordered_set>
 
 namespace
 {
@@ -91,6 +93,9 @@ TEST_CASE("hash<nlohmann::json>")
     // Collect hashes for different JSON values and make sure that they are distinct
     // We cannot compare against fixed values, because the implementation of
     // std::hash may differ between compilers.
+    //
+    // numbers that compare equal under operator== (0 == 0U == 0.0) must hash
+    // equally, so they are only inserted once below and checked separately.
 
     std::set<std::size_t> hashes;
 
@@ -107,10 +112,7 @@ TEST_CASE("hash<nlohmann::json>")
 
     // number
     hashes.insert(std::hash<json> {}(json(0)));
-    hashes.insert(std::hash<json> {}(json(static_cast<unsigned>(0))));
-
     hashes.insert(std::hash<json> {}(json(-1)));
-    hashes.insert(std::hash<json> {}(json(0.0)));
     hashes.insert(std::hash<json> {}(json(42.23)));
 
     // array
@@ -132,7 +134,36 @@ TEST_CASE("hash<nlohmann::json>")
     // discarded
     hashes.insert(std::hash<json> {}(json(json::value_t::discarded)));
 
-    CHECK(hashes.size() == 21);
+    CHECK(hashes.size() == 19);
+
+    // numbers that compare equal under operator== must hash equally,
+    // regardless of which of number_integer, number_unsigned, or
+    // number_float actually holds the value
+    CHECK(json(0) == json(static_cast<unsigned>(0)));
+    CHECK(json(0) == json(0.0));
+    CHECK(std::hash<json> {}(json(0)) == std::hash<json> {}(json(static_cast<unsigned>(0))));
+    CHECK(std::hash<json> {}(json(0)) == std::hash<json> {}(json(0.0)));
+    CHECK(std::hash<json> {}(json(-1)) == std::hash<json> {}(json(-1.0)));
+
+    // a std::unordered_set relies on this same consistency between == and hash
+    const std::unordered_set<json> numbers {json(0), json(static_cast<unsigned>(0)), json(0.0)};
+    CHECK(numbers.size() == 1);
+
+    // -0.0 compares equal to 0 and 0.0
+    CHECK(json(-0.0) == json(0));
+    CHECK(std::hash<json> {}(json(-0.0)) == std::hash<json> {}(json(0)));
+    CHECK(std::hash<json> {}(json(-0.0)) == std::hash<json> {}(json(0.0)));
+
+    // the ends of the integer ranges, which equal floats exactly
+    const auto int_min = (std::numeric_limits<json::number_integer_t>::min)();
+    const auto int_max = (std::numeric_limits<json::number_integer_t>::max)();
+    const auto two_63 = json::number_unsigned_t(1) << 63U;
+    CHECK(json(int_min) == json(-9223372036854775808.0));
+    CHECK(std::hash<json> {}(json(int_min)) == std::hash<json> {}(json(-9223372036854775808.0)));
+    CHECK(json(two_63) == json(9223372036854775808.0));
+    CHECK(std::hash<json> {}(json(two_63)) == std::hash<json> {}(json(9223372036854775808.0)));
+    CHECK(json(json::number_unsigned_t(int_max)) == json(int_max));
+    CHECK(std::hash<json> {}(json(json::number_unsigned_t(int_max))) == std::hash<json> {}(json(int_max)));
 }
 
 TEST_CASE("hash<nlohmann::ordered_json>")
@@ -156,10 +187,7 @@ TEST_CASE("hash<nlohmann::ordered_json>")
 
     // number
     hashes.insert(std::hash<ordered_json> {}(ordered_json(0)));
-    hashes.insert(std::hash<ordered_json> {}(ordered_json(static_cast<unsigned>(0))));
-
     hashes.insert(std::hash<ordered_json> {}(ordered_json(-1)));
-    hashes.insert(std::hash<ordered_json> {}(ordered_json(0.0)));
     hashes.insert(std::hash<ordered_json> {}(ordered_json(42.23)));
 
     // array
@@ -181,7 +209,10 @@ TEST_CASE("hash<nlohmann::ordered_json>")
     // discarded
     hashes.insert(std::hash<ordered_json> {}(ordered_json(ordered_json::value_t::discarded)));
 
-    CHECK(hashes.size() == 21);
+    CHECK(hashes.size() == 19);
+
+    CHECK(std::hash<ordered_json> {}(ordered_json(0)) == std::hash<ordered_json> {}(ordered_json(static_cast<unsigned>(0))));
+    CHECK(std::hash<ordered_json> {}(ordered_json(0)) == std::hash<ordered_json> {}(ordered_json(0.0)));
 }
 
 TEST_CASE("hash of deeply nested values")