Debian Codegraph @

Doc/c-api/number.rst

raw
1 .. highlight:: c
2
3 .. _number:
4
5 Number Protocol
6 ===============
7
8
9 .. c:function:: int PyNumber_Check(PyObject *o)
10
11 Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
12 This function always succeeds.
13
14 .. versionchanged:: 3.8
15 Returns ``1`` if *o* is an index integer.
16
17
18 .. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
19
20 Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. This is the
21 equivalent of the Python expression ``o1 + o2``.
22
23
24 .. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
25
26 Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. This is
27 the equivalent of the Python expression ``o1 - o2``.
28
29
30 .. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
31
32 Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. This is
33 the equivalent of the Python expression ``o1 * o2``.
34
35
36 .. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
37
38 Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on
39 failure. This is the equivalent of the Python expression ``o1 @ o2``.
40
41 .. versionadded:: 3.5
42
43
44 .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
45
46 Return the floor of *o1* divided by *o2*, or ``NULL`` on failure. This is
47 the equivalent of the Python expression ``o1 // o2``.
48
49
50 .. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
51
52 Return a reasonable approximation for the mathematical value of *o1* divided by
53 *o2*, or ``NULL`` on failure. The return value is "approximate" because binary
54 floating-point numbers are approximate; it is not possible to represent all real
55 numbers in base two. This function can return a floating-point value when
56 passed two integers. This is the equivalent of the Python expression ``o1 / o2``.
57
58
59 .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
60
61 Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. This is
62 the equivalent of the Python expression ``o1 % o2``.
63
64
65 .. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
66
67 .. index:: pair: built-in function; divmod
68
69 See the built-in function :func:`divmod`. Returns ``NULL`` on failure. This is
70 the equivalent of the Python expression ``divmod(o1, o2)``.
71
72
73 .. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
74
75 .. index:: pair: built-in function; pow
76
77 See the built-in function :func:`pow`. Returns ``NULL`` on failure. This is the
78 equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
79 If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing ``NULL`` for
80 *o3* would cause an illegal memory access).
81
82
83 .. c:function:: PyObject* PyNumber_Negative(PyObject *o)
84
85 Returns the negation of *o* on success, or ``NULL`` on failure. This is the
86 equivalent of the Python expression ``-o``.
87
88
89 .. c:function:: PyObject* PyNumber_Positive(PyObject *o)
90
91 Returns *o* on success, or ``NULL`` on failure. This is the equivalent of the
92 Python expression ``+o``.
93
94
95 .. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
96
97 .. index:: pair: built-in function; abs
98
99 Returns the absolute value of *o*, or ``NULL`` on failure. This is the equivalent
100 of the Python expression ``abs(o)``.
101
102
103 .. c:function:: PyObject* PyNumber_Invert(PyObject *o)
104
105 Returns the bitwise negation of *o* on success, or ``NULL`` on failure. This is
106 the equivalent of the Python expression ``~o``.
107
108
109 .. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
110
111 Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on
112 failure. This is the equivalent of the Python expression ``o1 << o2``.
113
114
115 .. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
116
117 Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on
118 failure. This is the equivalent of the Python expression ``o1 >> o2``.
119
120
121 .. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
122
123 Returns the "bitwise and" of *o1* and *o2* on success and ``NULL`` on failure.
124 This is the equivalent of the Python expression ``o1 & o2``.
125
126
127 .. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
128
129 Returns the "bitwise exclusive or" of *o1* by *o2* on success, or ``NULL`` on
130 failure. This is the equivalent of the Python expression ``o1 ^ o2``.
131
132
133 .. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
134
135 Returns the "bitwise or" of *o1* and *o2* on success, or ``NULL`` on failure.
136 This is the equivalent of the Python expression ``o1 | o2``.
137
138
139 .. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
140
141 Returns the result of adding *o1* and *o2*, or ``NULL`` on failure. The operation
142 is done *in-place* when *o1* supports it. This is the equivalent of the Python
143 statement ``o1 += o2``.
144
145
146 .. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
147
148 Returns the result of subtracting *o2* from *o1*, or ``NULL`` on failure. The
149 operation is done *in-place* when *o1* supports it. This is the equivalent of
150 the Python statement ``o1 -= o2``.
151
152
153 .. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
154
155 Returns the result of multiplying *o1* and *o2*, or ``NULL`` on failure. The
156 operation is done *in-place* when *o1* supports it. This is the equivalent of
157 the Python statement ``o1 *= o2``.
158
159
160 .. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
161
162 Returns the result of matrix multiplication on *o1* and *o2*, or ``NULL`` on
163 failure. The operation is done *in-place* when *o1* supports it. This is
164 the equivalent of the Python statement ``o1 @= o2``.
165
166 .. versionadded:: 3.5
167
168
169 .. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
170
171 Returns the mathematical floor of dividing *o1* by *o2*, or ``NULL`` on failure.
172 The operation is done *in-place* when *o1* supports it. This is the equivalent
173 of the Python statement ``o1 //= o2``.
174
175
176 .. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
177
178 Return a reasonable approximation for the mathematical value of *o1* divided by
179 *o2*, or ``NULL`` on failure. The return value is "approximate" because binary
180 floating-point numbers are approximate; it is not possible to represent all real
181 numbers in base two. This function can return a floating-point value when
182 passed two integers. The operation is done *in-place* when *o1* supports it.
183 This is the equivalent of the Python statement ``o1 /= o2``.
184
185
186 .. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
187
188 Returns the remainder of dividing *o1* by *o2*, or ``NULL`` on failure. The
189 operation is done *in-place* when *o1* supports it. This is the equivalent of
190 the Python statement ``o1 %= o2``.
191
192
193 .. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
194
195 .. index:: pair: built-in function; pow
196
197 See the built-in function :func:`pow`. Returns ``NULL`` on failure. The operation
198 is done *in-place* when *o1* supports it. This is the equivalent of the Python
199 statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
200 ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
201 in its place (passing ``NULL`` for *o3* would cause an illegal memory access).
202
203
204 .. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
205
206 Returns the result of left shifting *o1* by *o2* on success, or ``NULL`` on
207 failure. The operation is done *in-place* when *o1* supports it. This is the
208 equivalent of the Python statement ``o1 <<= o2``.
209
210
211 .. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
212
213 Returns the result of right shifting *o1* by *o2* on success, or ``NULL`` on
214 failure. The operation is done *in-place* when *o1* supports it. This is the
215 equivalent of the Python statement ``o1 >>= o2``.
216
217
218 .. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
219
220 Returns the "bitwise and" of *o1* and *o2* on success and ``NULL`` on failure. The
221 operation is done *in-place* when *o1* supports it. This is the equivalent of
222 the Python statement ``o1 &= o2``.
223
224
225 .. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
226
227 Returns the "bitwise exclusive or" of *o1* by *o2* on success, or ``NULL`` on
228 failure. The operation is done *in-place* when *o1* supports it. This is the
229 equivalent of the Python statement ``o1 ^= o2``.
230
231
232 .. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
233
234 Returns the "bitwise or" of *o1* and *o2* on success, or ``NULL`` on failure. The
235 operation is done *in-place* when *o1* supports it. This is the equivalent of
236 the Python statement ``o1 |= o2``.
237
238
239 .. c:function:: PyObject* PyNumber_Long(PyObject *o)
240
241 .. index:: pair: built-in function; int
242
243 Returns the *o* converted to an integer object on success, or ``NULL`` on
244 failure. This is the equivalent of the Python expression ``int(o)``.
245
246
247 .. c:function:: PyObject* PyNumber_Float(PyObject *o)
248
249 .. index:: pair: built-in function; float
250
251 Returns the *o* converted to a float object on success, or ``NULL`` on failure.
252 This is the equivalent of the Python expression ``float(o)``.
253
254
255 .. c:function:: PyObject* PyNumber_Index(PyObject *o)
256
257 Returns the *o* converted to a Python int on success or ``NULL`` with a
258 :exc:`TypeError` exception raised on failure.
259
260 .. versionchanged:: 3.10
261 The result always has exact type :class:`int`. Previously, the result
262 could have been an instance of a subclass of ``int``.
263
264
265 .. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
266
267 Returns the integer *n* converted to base *base* as a string. The *base*
268 argument must be one of 2, 8, 10, or 16. For base 2, 8, or 16, the
269 returned string is prefixed with a base marker of ``'0b'``, ``'0o'``, or
270 ``'0x'``, respectively. If *n* is not a Python int, it is converted with
271 :c:func:`PyNumber_Index` first.
272
273
274 .. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
275
276 Returns *o* converted to a :c:type:`Py_ssize_t` value if *o* can be interpreted as an
277 integer. If the call fails, an exception is raised and ``-1`` is returned.
278
279 If *o* can be converted to a Python int but the attempt to
280 convert to a :c:type:`Py_ssize_t` value would raise an :exc:`OverflowError`, then the
281 *exc* argument is the type of exception that will be raised (usually
282 :exc:`IndexError` or :exc:`OverflowError`). If *exc* is ``NULL``, then the
283 exception is cleared and the value is clipped to ``PY_SSIZE_T_MIN`` for a negative
284 integer or ``PY_SSIZE_T_MAX`` for a positive integer.
285
286
287 .. c:function:: int PyIndex_Check(PyObject *o)
288
289 Returns ``1`` if *o* is an index integer (has the ``nb_index`` slot of the
290 ``tp_as_number`` structure filled in), and ``0`` otherwise.
291 This function always succeeds.