Debian Codegraph @

Doc/c-api/hash.rst

raw
1 .. highlight:: c
2
3 PyHash API
4 ----------
5
6 See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
7
8 .. c:type:: Py_hash_t
9
10 Hash value type: signed integer.
11
12 .. versionadded:: 3.2
13
14
15 .. c:type:: Py_uhash_t
16
17 Hash value type: unsigned integer.
18
19 .. versionadded:: 3.2
20
21
22 .. c:macro:: Py_HASH_ALGORITHM
23
24 A numerical value indicating the algorithm for hashing of :class:`str`,
25 :class:`bytes`, and :class:`memoryview`.
26
27 The algorithm name is exposed by :data:`sys.hash_info.algorithm`.
28
29 .. versionadded:: 3.4
30
31
32 .. c:macro:: Py_HASH_FNV
33 Py_HASH_SIPHASH24
34 Py_HASH_SIPHASH13
35
36 Numerical values to compare to :c:macro:`Py_HASH_ALGORITHM` to determine
37 which algorithm is used for hashing. The hash algorithm can be configured
38 via the configure :option:`--with-hash-algorithm` option.
39
40 .. versionadded:: 3.4
41 Add :c:macro:`!Py_HASH_FNV` and :c:macro:`!Py_HASH_SIPHASH24`.
42
43 .. versionadded:: 3.11
44 Add :c:macro:`!Py_HASH_SIPHASH13`.
45
46
47 .. c:macro:: Py_HASH_CUTOFF
48
49 Buffers of length in range ``[1, Py_HASH_CUTOFF)`` are hashed using DJBX33A
50 instead of the algorithm described by :c:macro:`Py_HASH_ALGORITHM`.
51
52 - A :c:macro:`!Py_HASH_CUTOFF` of 0 disables the optimization.
53 - :c:macro:`!Py_HASH_CUTOFF` must be non-negative and less or equal than 7.
54
55 32-bit platforms should use a cutoff smaller than 64-bit platforms because
56 it is easier to create colliding strings. A cutoff of 7 on 64-bit platforms
57 and 5 on 32-bit platforms should provide a decent safety margin.
58
59 This corresponds to the :data:`sys.hash_info.cutoff` constant.
60
61 .. versionadded:: 3.4
62
63
64 .. c:macro:: PyHASH_MODULUS
65
66 The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``,
67 used for numeric hash scheme.
68
69 This corresponds to the :data:`sys.hash_info.modulus` constant.
70
71 .. versionadded:: 3.13
72
73
74 .. c:macro:: PyHASH_BITS
75
76 The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`.
77
78 .. versionadded:: 3.13
79
80
81 .. c:macro:: PyHASH_MULTIPLIER
82
83 Prime multiplier used in string and various other hashes.
84
85 .. versionadded:: 3.13
86
87
88 .. c:macro:: PyHASH_INF
89
90 The hash value returned for a positive infinity.
91
92 This corresponds to the :data:`sys.hash_info.inf` constant.
93
94 .. versionadded:: 3.13
95
96
97 .. c:macro:: PyHASH_IMAG
98
99 The multiplier used for the imaginary part of a complex number.
100
101 This corresponds to the :data:`sys.hash_info.imag` constant.
102
103 .. versionadded:: 3.13
104
105
106 .. c:type:: PyHash_FuncDef
107
108 Hash function definition used by :c:func:`PyHash_GetFuncDef`.
109
110 .. c:member:: Py_hash_t (*const hash)(const void *, Py_ssize_t)
111
112 Hash function.
113
114 .. c:member:: const char *name
115
116 Hash function name (UTF-8 encoded string).
117
118 This corresponds to the :data:`sys.hash_info.algorithm` constant.
119
120 .. c:member:: const int hash_bits
121
122 Internal size of the hash value in bits.
123
124 This corresponds to the :data:`sys.hash_info.hash_bits` constant.
125
126 .. c:member:: const int seed_bits
127
128 Size of seed input in bits.
129
130 This corresponds to the :data:`sys.hash_info.seed_bits` constant.
131
132 .. versionadded:: 3.4
133
134
135 .. c:function:: PyHash_FuncDef* PyHash_GetFuncDef(void)
136
137 Get the hash function definition.
138
139 .. seealso::
140 :pep:`456` "Secure and interchangeable hash algorithm".
141
142 .. versionadded:: 3.4
143
144
145 .. c:function:: Py_hash_t Py_HashPointer(const void *ptr)
146
147 Hash a pointer value: process the pointer value as an integer (cast it to
148 ``uintptr_t`` internally). The pointer is not dereferenced.
149
150 The function cannot fail: it cannot return ``-1``.
151
152 .. versionadded:: 3.13
153
154
155 .. c:function:: Py_hash_t Py_HashBuffer(const void *ptr, Py_ssize_t len)
156
157 Compute and return the hash value of a buffer of *len* bytes
158 starting at address *ptr*. The hash is guaranteed to match that of
159 :class:`bytes`, :class:`memoryview`, and other built-in objects
160 that implement the :ref:`buffer protocol <bufferobjects>`.
161
162 Use this function to implement hashing for immutable objects whose
163 :c:member:`~PyTypeObject.tp_richcompare` function compares to another
164 object's buffer.
165
166 *len* must be greater than or equal to ``0``.
167
168 This function always succeeds.
169
170 .. versionadded:: 3.14
171
172
173 .. c:function:: Py_hash_t PyObject_GenericHash(PyObject *obj)
174
175 Generic hashing function that is meant to be put into a type
176 object's ``tp_hash`` slot.
177 Its result only depends on the object's identity.
178
179 .. impl-detail::
180 In CPython, it is equivalent to :c:func:`Py_HashPointer`.
181
182 .. versionadded:: 3.13