mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-12-23 09:19:18 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

[3.13] gh-141004: Document Py_HASH_* macros (GH-141205) (#141224)

Browse source 
* gh-141004: Document `Py_HASH_*` macros (GH-141205)

(cherry picked from commit 3989e12d39)
(cherry picked from commit 8cec3d3a9d)

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
This commit is contained in:
Miss Islington (bot) 2025-11-08 10:22:02 +01:00 • committed by GitHub
parent dfbc5eb80e
commit a728f7f89f
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 53 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

54
Doc/c-api/hash.rst
View file

@ -11,42 +11,94 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
.. versionadded:: 3.2
.. c:type:: Py_uhash_t
Hash value type: unsigned integer.
.. versionadded:: 3.2
.. c:macro:: Py_HASH_ALGORITHM
A numerical value indicating the algorithm for hashing of :class:`str`,
:class:`bytes`, and :class:`memoryview`.
The algorithm name is exposed by :data:`sys.hash_info.algorithm`.
.. versionadded:: 3.4
.. c:macro:: Py_HASH_FNV
Py_HASH_SIPHASH24
Py_HASH_SIPHASH13
Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine
which algorithm is used for hashing. The hash algorithm can be configured
via the configure :option:`--with-hash-algorithm` option.
.. versionadded:: 3.4
Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`.
.. versionadded:: 3.11
Add :c:macro:`!Py_HASH_SIPHASH13`.
.. c:macro:: Py_HASH_CUTOFF
Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A
instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`.
- A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization.
- :c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7.
32-bit platforms should use a cutoff smaller than 64-bit platforms because
it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms
and 5 on 32-bit platforms should provide a decent safety margin.
.. versionadded:: 3.4
.. c:macro:: PyHASH_MODULUS
The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``, used for numeric hash scheme.
The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``,
used for numeric hash scheme.
This corresponds to the :data:`sys.hash_info.modulus` constant.
.. versionadded:: 3.13
.. c:macro:: PyHASH_BITS
The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`.
This corresponds to the :data:`sys.hash_info.hash_bits` constant.
.. versionadded:: 3.13
.. c:macro:: PyHASH_MULTIPLIER
Prime multiplier used in string and various other hashes.
.. versionadded:: 3.13
.. c:macro:: PyHASH_INF
The hash value returned for a positive infinity.
This corresponds to the :data:`sys.hash_info.inf` constant.
.. versionadded:: 3.13
.. c:macro:: PyHASH_IMAG
The multiplier used for the imaginary part of a complex number.
This corresponds to the :data:`sys.hash_info.imag` constant.
.. versionadded:: 3.13
.. c:type:: PyHash_FuncDef
Hash function definition used by :c:func:`PyHash_GetFuncDef`.