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