#
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)`".