gh-111545: Add PyHash_Double() function

* Cleanup PyHash_Double() implementation based _Py_HashDouble():

  * Move variable declaration to their first assignment.
  * Add braces (PEP 7).
  * Cast result to signed Py_hash_t before the final "== -1" test, to
    reduce the number of casts.
  * Add an assertion on Py_IS_NAN(v) in the only code path which can
    return -1.

* Add tests: Modules/_testcapi/hash.c and
  Lib/test/test_capi/test_hash.py.

Author: vstinner

Doc/c-api/hash.rst

@@ -0,0 +1,12 @@
+.. highlight:: c
+
+PyHash API
+----------
+
+See also the :c:member:`PyTypeObject.tp_hash` member.
+
+.. c:function:: Py_hash_t PyHash_Double(double value)
+
+   Hash a C double number.
+
+   Return ``-1`` if *value* is not-a-number (NaN).

Doc/c-api/utilities.rst

@@ -17,6 +17,7 @@ and parsing function arguments and constructing Python values from C values.
    marshal.rst
    arg.rst
    conversion.rst
+   hash.rst
    reflection.rst
    codec.rst
    perfmaps.rst

Doc/whatsnew/3.13.rst

@@ -1181,6 +1181,9 @@ New Features
   :exc:`KeyError` if the key missing.
   (Contributed by Stefan Behnel and Victor Stinner in :gh:`111262`.)
 
+* Add :c:func:`PyHash_Double` function to hash a C double number.
+  (Contributed by Victor Stinner in :gh:`111545`.)
+
 
 Porting to Python 3.13
 ----------------------

Include/cpython/pyhash.h

@@ -11,3 +11,5 @@ typedef struct {
 } PyHash_FuncDef;
 
 PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);
+
+PyAPI_FUNC(Py_hash_t) PyHash_Double(double value);

Lib/test/test_capi/test_hash.py

@@ -0,0 +1,61 @@
+import math
+import sys
+import unittest
+from test.support import import_helper
+_testcapi = import_helper.import_module('_testcapi')
+
+
+PyHASH_INF = sys.hash_info.inf
+if _testcapi.SIZEOF_VOID_P >= 8:
+    PyHASH_BITS = 61
+else:
+    PyHASH_BITS = 31
+PyHASH_MODULUS = ((1 << PyHASH_BITS) - 1)
+
+
+class CAPITest(unittest.TestCase):
+    def test_hash_double(self):
+        # Test PyHash_Double()
+        hash_double = _testcapi.hash_double
+
+        # test integers
+        def python_hash_int(x):
+            negative = (x < 0)
+            x = abs(x) % PyHASH_MODULUS
+            if negative:
+                x = -x
+            if x == -1:
+                x = -2
+            return x
+
+        integers = [
+            *range(1, 30),
+            2**30 - 1,
+            2 ** 233,
+            int(sys.float_info.max),
+        ]
+        integers.extend([-x for x in integers])
+        integers.append(0)
+
+        for x in integers:
+            self.assertEqual(hash_double(float(x)), python_hash_int(x), x)
+
+        # test non-finite values
+        self.assertEqual(hash_double(float('inf')), PyHASH_INF)
+        self.assertEqual(hash_double(float('-inf')), -PyHASH_INF)
+        self.assertEqual(hash_double(float('nan')), -1)
+
+        # special values: compare with Python hash() function
+        def python_hash_double(x):
+            return hash(x)
+
+        special_values = (
+            sys.float_info.max,
+            sys.float_info.min,
+            sys.float_info.epsilon,
+            math.nextafter(0.0, 1.0),
+        )
+        for x in special_values:
+            with self.subTest(x=x):
+                self.assertEqual(hash_double(x), python_hash_double(x))
+                self.assertEqual(hash_double(-x), python_hash_double(-x))

Misc/NEWS.d/next/C API/2023-11-15-01-26-59.gh-issue-111545.iAoFtA.rst

@@ -0,0 +1,2 @@
+Add :c:func:`PyHash_Double` function to hash a C double number. Patch by
+Victor Stinner.

Modules/Setup.stdlib.in

@@ -159,7 +159,7 @@
 @MODULE__XXTESTFUZZ_TRUE@_xxtestfuzz _xxtestfuzz/_xxtestfuzz.c _xxtestfuzz/fuzzer.c
 @MODULE__TESTBUFFER_TRUE@_testbuffer _testbuffer.c
 @MODULE__TESTINTERNALCAPI_TRUE@_testinternalcapi _testinternalcapi.c _testinternalcapi/test_lock.c _testinternalcapi/pytime.c _testinternalcapi/set.c _testinternalcapi/test_critical_sections.c
-@MODULE__TESTCAPI_TRUE@_testcapi _testcapimodule.c _testcapi/vectorcall.c _testcapi/vectorcall_limited.c _testcapi/heaptype.c _testcapi/abstract.c _testcapi/bytearray.c _testcapi/bytes.c _testcapi/unicode.c _testcapi/dict.c _testcapi/set.c _testcapi/list.c _testcapi/tuple.c _testcapi/getargs.c _testcapi/datetime.c _testcapi/docstring.c _testcapi/mem.c _testcapi/watchers.c _testcapi/long.c _testcapi/float.c _testcapi/complex.c _testcapi/numbers.c _testcapi/structmember.c _testcapi/exceptions.c _testcapi/code.c _testcapi/buffer.c _testcapi/pyatomic.c _testcapi/pyos.c _testcapi/file.c _testcapi/codec.c _testcapi/immortal.c _testcapi/heaptype_relative.c _testcapi/gc.c _testcapi/sys.c
+@MODULE__TESTCAPI_TRUE@_testcapi _testcapimodule.c _testcapi/vectorcall.c _testcapi/vectorcall_limited.c _testcapi/heaptype.c _testcapi/abstract.c _testcapi/bytearray.c _testcapi/bytes.c _testcapi/unicode.c _testcapi/dict.c _testcapi/set.c _testcapi/list.c _testcapi/tuple.c _testcapi/getargs.c _testcapi/datetime.c _testcapi/docstring.c _testcapi/mem.c _testcapi/watchers.c _testcapi/long.c _testcapi/float.c _testcapi/complex.c _testcapi/numbers.c _testcapi/structmember.c _testcapi/exceptions.c _testcapi/code.c _testcapi/buffer.c _testcapi/pyatomic.c _testcapi/pyos.c _testcapi/file.c _testcapi/codec.c _testcapi/immortal.c _testcapi/heaptype_relative.c _testcapi/gc.c _testcapi/sys.c _testcapi/hash.c
 @MODULE__TESTCLINIC_TRUE@_testclinic _testclinic.c
 @MODULE__TESTCLINIC_LIMITED_TRUE@_testclinic_limited _testclinic_limited.c
 

Modules/_testcapi/hash.c

@@ -0,0 +1,25 @@
+#include "parts.h"
+#include "util.h"
+
+static PyObject *
+hash_double(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    double value;
+    if (!PyArg_ParseTuple(args, "d", &value)) {
+        return NULL;
+    }
+    Py_hash_t hash = PyHash_Double(value);
+    Py_BUILD_ASSERT(sizeof(long long) >= sizeof(hash));
+    return PyLong_FromLongLong(hash);
+}
+
+static PyMethodDef test_methods[] = {
+    {"hash_double", hash_double, METH_VARARGS},
+    {NULL},
+};
+
+int
+_PyTestCapi_Init_Hash(PyObject *m)
+{
+    return PyModule_AddFunctions(m, test_methods);
+}

Modules/_testcapi/parts.h

@@ -58,6 +58,7 @@ int _PyTestCapi_Init_Codec(PyObject *module);
 int _PyTestCapi_Init_Immortal(PyObject *module);
 int _PyTestCapi_Init_GC(PyObject *module);
 int _PyTestCapi_Init_Sys(PyObject *module);
+int _PyTestCapi_Init_Hash(PyObject *module);
 
 int _PyTestCapi_Init_VectorcallLimited(PyObject *module);
 int _PyTestCapi_Init_HeaptypeRelative(PyObject *module);

Modules/_testcapimodule.c

@@ -3995,6 +3995,9 @@ PyInit__testcapi(void)
     if (_PyTestCapi_Init_HeaptypeRelative(m) < 0) {
         return NULL;
     }
+    if (_PyTestCapi_Init_Hash(m) < 0) {
+        return NULL;
+    }
 
     PyState_AddModule(m, &_testcapimodule);
     return m;