| 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. |