6.2 Number Protocol
Keywords: api

#
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_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 expression "`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 expression "`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 expression "`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 expression "`o1 /= o2`".

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 expression "`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 expression "`o1 **= o2`" when o3 is `Py_None`, or an in-place variant of "`pow(o1, o2, varo3)`" 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 expression "`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 expression "`o1 »= o2`".

PyObject* `PyNumber_InPlaceAnd` (PyObject *o1, PyObject *o2)
  Return value: New reference.
  Returns the ``bitwise and'' of o2 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 expression "`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 expression "`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 expression "`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)`".