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_Divide(PyObject *o1, PyObject *o2) 34 35 Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the 36 equivalent of the Python expression ``o1 / o2``. 37 38 39 .. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2) 40 41 Return the floor of *o1* divided by *o2*, or *NULL* on failure. This is 42 equivalent to the "classic" division of integers. 43 44 .. versionadded:: 2.2 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 .. versionadded:: 2.2 56 57 58 .. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2) 59 60 Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure. This is 61 the equivalent of the Python expression ``o1 % o2``. 62 63 64 .. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2) 65 66 .. index:: builtin: divmod 67 68 See the built-in function :func:`divmod`. Returns *NULL* on failure. This is 69 the equivalent of the Python expression ``divmod(o1, o2)``. 70 71 72 .. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3) 73 74 .. index:: builtin: pow 75 76 See the built-in function :func:`pow`. Returns *NULL* on failure. This is the 77 equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional. 78 If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for 79 *o3* would cause an illegal memory access). 80 81 82 .. c:function:: PyObject* PyNumber_Negative(PyObject *o) 83 84 Returns the negation of *o* on success, or *NULL* on failure. This is the 85 equivalent of the Python expression ``-o``. 86 87 88 .. c:function:: PyObject* PyNumber_Positive(PyObject *o) 89 90 Returns *o* on success, or *NULL* on failure. This is the equivalent of the 91 Python expression ``+o``. 92 93 94 .. c:function:: PyObject* PyNumber_Absolute(PyObject *o) 95 96 .. index:: builtin: abs 97 98 Returns the absolute value of *o*, or *NULL* on failure. This is the equivalent 99 of the Python expression ``abs(o)``. 100 101 102 .. c:function:: PyObject* PyNumber_Invert(PyObject *o) 103 104 Returns the bitwise negation of *o* on success, or *NULL* on failure. This is 105 the equivalent of the Python expression ``~o``. 106 107 108 .. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2) 109 110 Returns the result of left shifting *o1* by *o2* on success, or *NULL* on 111 failure. This is the equivalent of the Python expression ``o1 << o2``. 112 113 114 .. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2) 115 116 Returns the result of right shifting *o1* by *o2* on success, or *NULL* on 117 failure. This is the equivalent of the Python expression ``o1 >> o2``. 118 119 120 .. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2) 121 122 Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. 123 This is the equivalent of the Python expression ``o1 & o2``. 124 125 126 .. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2) 127 128 Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on 129 failure. This is the equivalent of the Python expression ``o1 ^ o2``. 130 131 132 .. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2) 133 134 Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure. 135 This is the equivalent of the Python expression ``o1 | o2``. 136 137 138 .. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2) 139 140 Returns the result of adding *o1* and *o2*, or *NULL* on failure. The operation 141 is done *in-place* when *o1* supports it. This is the equivalent of the Python 142 statement ``o1 += o2``. 143 144 145 .. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2) 146 147 Returns the result of subtracting *o2* from *o1*, or *NULL* on failure. The 148 operation is done *in-place* when *o1* supports it. This is the equivalent of 149 the Python statement ``o1 -= o2``. 150 151 152 .. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2) 153 154 Returns the result of multiplying *o1* and *o2*, or *NULL* on failure. The 155 operation is done *in-place* when *o1* supports it. This is the equivalent of 156 the Python statement ``o1 *= o2``. 157 158 159 .. c:function:: PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2) 160 161 Returns the result of dividing *o1* by *o2*, or *NULL* on failure. The 162 operation is done *in-place* when *o1* supports it. This is the equivalent of 163 the Python statement ``o1 /= o2``. 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 .. versionadded:: 2.2 173 174 175 .. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2) 176 177 Return a reasonable approximation for the mathematical value of *o1* divided by 178 *o2*, or *NULL* on failure. The return value is "approximate" because binary 179 floating point numbers are approximate; it is not possible to represent all real 180 numbers in base two. This function can return a floating point value when 181 passed two integers. The operation is done *in-place* when *o1* supports it. 182 183 .. versionadded:: 2.2 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:: builtin: 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:: int PyNumber_Coerce(PyObject **p1, PyObject **p2) 240 241 .. index:: builtin: coerce 242 243 This function takes the addresses of two variables of type :c:type:`PyObject\*`. 244 If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment 245 their reference count and return ``0`` (success). If the objects can be 246 converted to a common numeric type, replace ``*p1`` and ``*p2`` by their 247 converted value (with 'new' reference counts), and return ``0``. If no 248 conversion is possible, or if some other error occurs, return ``-1`` (failure) 249 and don't increment the reference counts. The call ``PyNumber_Coerce(&o1, 250 &o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``. 251 252 253 .. c:function:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2) 254 255 This function is similar to :c:func:`PyNumber_Coerce`, except that it returns 256 ``1`` when the conversion is not possible and when no error is raised. 257 Reference counts are still not increased in this case. 258 259 260 .. c:function:: PyObject* PyNumber_Int(PyObject *o) 261 262 .. index:: builtin: int 263 264 Returns the *o* converted to an integer object on success, or *NULL* on failure. 265 If the argument is outside the integer range a long object will be returned 266 instead. This is the equivalent of the Python expression ``int(o)``. 267 268 269 .. c:function:: PyObject* PyNumber_Long(PyObject *o) 270 271 .. index:: builtin: long 272 273 Returns the *o* converted to a long integer object on success, or *NULL* on 274 failure. This is the equivalent of the Python expression ``long(o)``. 275 276 277 .. c:function:: PyObject* PyNumber_Float(PyObject *o) 278 279 .. index:: builtin: float 280 281 Returns the *o* converted to a float object on success, or *NULL* on failure. 282 This is the equivalent of the Python expression ``float(o)``. 283 284 285 .. c:function:: PyObject* PyNumber_Index(PyObject *o) 286 287 Returns the *o* converted to a Python int or long on success or *NULL* with a 288 :exc:`TypeError` exception raised on failure. 289 290 .. versionadded:: 2.5 291 292 293 .. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base) 294 295 Returns the integer *n* converted to *base* as a string with a base 296 marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When 297 *base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the 298 base. If *n* is not an int object, it is converted with 299 :c:func:`PyNumber_Index` first. 300 301 .. versionadded:: 2.6 302 303 304 .. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc) 305 306 Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an 307 integer. If *o* can be converted to a Python int or long but the attempt to 308 convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the 309 *exc* argument is the type of exception that will be raised (usually 310 :exc:`IndexError` or :exc:`OverflowError`). If *exc* is *NULL*, then the 311 exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative 312 integer or *PY_SSIZE_T_MAX* for a positive integer. 313 314 .. versionadded:: 2.5 315 316 317 .. c:function:: int PyIndex_Check(PyObject *o) 318 319 Returns ``1`` if *o* is an index integer (has the nb_index slot of the 320 tp_as_number structure filled in), and ``0`` otherwise. 321 322 .. versionadded:: 2.5 323
