Python/C API Reference Manual

Previous: 6.1 Object Protocol Up: 6. Abstract Objects Layer Next: 6.3 Sequence Protocol

---

 
6.2 Number Protocol

int PyNumber_Check(PyObject *o)

Returns 1 if the object o provides numeric protocols, and false otherwise. This function always succeeds.

PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of adding o1 and o2, or NULL on failure. This is the equivalent of the Python expression "o1 + o2".

PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of subtracting o2 from o1, or NULL on failure. This is the equivalent of the Python expression "o1 - o2".

PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of multiplying o1 and o2, or NULL on failure. This is the equivalent of the Python expression "o1 * o2".

PyObject* PyNumber_Divide(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of dividing o1 by o2, or NULL on failure. This is the equivalent of the Python expression "o1 / o2".

PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return the floor of o1 divided by o2, or NULL on failure. This is equivalent to the ``classic'' division of integers. New in version 2.2.

PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return a reasonable approximation for the mathematical value of o1 divided by o2, or NULL on failure. The return value is ``approximate'' because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. New in version 2.2.

PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the remainder of dividing o1 by o2, or NULL on failure. This is the equivalent of the Python expression "o1 % o2".

PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)

Return value: New reference.

See the built-in function divmod()  Returns NULL on failure. This is the equivalent of the Python expression "divmod(o1, o2)".

PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference.

See the built-in function pow()  Returns NULL on failure. This is the equivalent of the Python expression "pow(o1, o2, o3)", where o3 is optional. If o3 is to be ignored, pass Py_None in its place (passing NULL for o3 would cause an illegal memory access).

PyObject* PyNumber_Negative(PyObject *o)

Return value: New reference.

Returns the negation of o on success, or NULL on failure. This is the equivalent of the Python expression "-o".

PyObject* PyNumber_Positive(PyObject *o)

Return value: New reference.

Returns o on success, or NULL on failure. This is the equivalent of the Python expression "+o".

PyObject* PyNumber_Absolute(PyObject *o)

Return value: New reference.

Returns the absolute value of o, or NULL on failure. This is the equivalent of the Python expression "abs(o)".

PyObject* PyNumber_Invert(PyObject *o)

Return value: New reference.

Returns the bitwise negation of o on success, or NULL on failure. This is the equivalent of the Python expression "~o".

PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of left shifting o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 << o2".

PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of right shifting o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 >> o2".

PyObject* PyNumber_And(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise and'' of o2 and o2 on success and NULL on failure. This is the equivalent of the Python expression "o1 & o2".

PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise exclusive or'' of o1 by o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 ^ o2".

PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise or'' of o1 and o2 on success, or NULL on failure. This is the equivalent of the Python expression "o1 | o2".

PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of adding o1 and o2, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 += o2".

PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of subtracting o2 from o1, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 -= o2".

PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of multiplying o1 and o2, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 *= o2".

PyObject* PyNumber_InPlaceDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of dividing o1 by o2, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 /= o2".

PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the mathematical of dividing o1 by o2, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 //= o2". New in version 2.2.

PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)

Return value: New reference.

Return a reasonable approximation for the mathematical value of o1 divided by o2, or NULL on failure. The return value is ``approximate'' because binary floating point numbers are approximate; it is not possible to represent all real numbers in base two. This function can return a floating point value when passed two integers. The operation is done in-place when o1 supports it. New in version 2.2.

PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the remainder of dividing o1 by o2, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 %= o2".

PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)

Return value: New reference.

See the built-in function pow().  Returns NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 **= o2" when o3 is Py_None, or an in-place variant of "pow(o1, o2, o3)" otherwise. If o3 is to be ignored, pass Py_None in its place (passing NULL for o3 would cause an illegal memory access).

PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of left shifting o1 by o2 on success, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 <<= o2".

PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the result of right shifting o1 by o2 on success, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 >>= o2".

PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise and'' of o1 and o2 on success and NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 &= o2".

PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise exclusive or'' of o1 by o2 on success, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 ^= o2".

PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)

Return value: New reference.

Returns the ``bitwise or'' of o1 and o2 on success, or NULL on failure. The operation is done in-place when o1 supports it. This is the equivalent of the Python statement "o1 |= o2".

int PyNumber_Coerce(PyObject **p1, PyObject **p2)

This function takes the addresses of two variables of type PyObject*. If the objects pointed to by *p1 and *p2 have the same type, increment their reference count and return 0 (success). If the objects can be converted to a common numeric type, replace *p1 and *p2 by their converted value (with 'new' reference counts), and return 0. If no conversion is possible, or if some other error occurs, return -1 (failure) and don't increment the reference counts. The call PyNumber_Coerce(&o1, &o2) is equivalent to the Python statement "o1, o2 = coerce(o1, o2)".

PyObject* PyNumber_Int(PyObject *o)

Return value: New reference.

Returns the o converted to an integer object on success, or NULL on failure. This is the equivalent of the Python expression "int(o)". 

PyObject* PyNumber_Long(PyObject *o)

Return value: New reference.

Returns the o converted to a long integer object on success, or NULL on failure. This is the equivalent of the Python expression "long(o)". 

PyObject* PyNumber_Float(PyObject *o)

Return value: New reference.

Returns the o converted to a float object on success, or NULL on failure. This is the equivalent of the Python expression "float(o)". 

---

Python/C API Reference Manual

Previous: 6.1 Object Protocol Up: 6. Abstract Objects Layer Next: 6.3 Sequence Protocol

---

Release 2.2.2, documentation updated on October 14, 2002.