
Integer Objects
***************

All integers are implemented as "long" integer objects of arbitrary
size.

PyLongObject

   This subtype of "PyObject" represents a Python integer object.

PyTypeObject PyLong_Type

   This instance of "PyTypeObject" represents the Python integer type.
   This is the same object as "int" in the Python layer.

int PyLong_Check(PyObject *p)

   Return true if its argument is a "PyLongObject" or a subtype of
   "PyLongObject".

int PyLong_CheckExact(PyObject *p)

   Return true if its argument is a "PyLongObject", but not a subtype
   of "PyLongObject".

PyObject* PyLong_FromLong(long v)
    *Return value: New reference.*

   Return a new "PyLongObject" object from *v*, or *NULL* on failure.

   The current implementation keeps an array of integer objects for
   all integers between "-5" and "256", when you create an int in that
   range you actually just get back a reference to the existing
   object. So it should be possible to change the value of "1".  I
   suspect the behaviour of Python in this case is undefined. :-)

PyObject* PyLong_FromUnsignedLong(unsigned long v)
    *Return value: New reference.*

   Return a new "PyLongObject" object from a C "unsigned long", or
   *NULL* on failure.

PyObject* PyLong_FromSsize_t(Py_ssize_t v)

   Return a new "PyLongObject" object from a C "Py_ssize_t", or *NULL*
   on failure.

PyObject* PyLong_FromSize_t(size_t v)

   Return a new "PyLongObject" object from a C "size_t", or *NULL* on
   failure.

PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
    *Return value: New reference.*

   Return a new "PyLongObject" object from a C "long long", or *NULL*
   on failure.

PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
    *Return value: New reference.*

   Return a new "PyLongObject" object from a C "unsigned long long",
   or *NULL* on failure.

PyObject* PyLong_FromDouble(double v)
    *Return value: New reference.*

   Return a new "PyLongObject" object from the integer part of *v*, or
   *NULL* on failure.

PyObject* PyLong_FromString(char *str, char **pend, int base)
    *Return value: New reference.*

   Return a new "PyLongObject" based on the string value in *str*,
   which is interpreted according to the radix in *base*.  If *pend*
   is non-*NULL*, **pend* will point to the first character in *str*
   which follows the representation of the number.  If *base* is "0",
   the radix will be determined based on the leading characters of
   *str*: if *str* starts with "'0x'" or "'0X'", radix 16 will be
   used; if *str* starts with "'0o'" or "'0O'", radix 8 will be used;
   if *str* starts with "'0b'" or "'0B'", radix 2 will be used;
   otherwise radix 10 will be used.  If *base* is not "0", it must be
   between "2" and "36", inclusive.  Leading spaces are ignored.  If
   there are no digits, "ValueError" will be raised.

PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
    *Return value: New reference.*

   Convert a sequence of Unicode digits to a Python integer value.
   The Unicode string is first encoded to a byte string using
   "PyUnicode_EncodeDecimal()" and then converted using
   "PyLong_FromString()".

   Deprecated since version 3.3, will be removed in version 4.0: Part
   of the old-style "Py_UNICODE" API; please migrate to using
   "PyLong_FromUnicodeObject()".

PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)

   Convert a sequence of Unicode digits in the string *u* to a Python
   integer value.  The Unicode string is first encoded to a byte
   string using "PyUnicode_EncodeDecimal()" and then converted using
   "PyLong_FromString()".

   New in version 3.3.

PyObject* PyLong_FromVoidPtr(void *p)
    *Return value: New reference.*

   Create a Python integer from the pointer *p*. The pointer value can
   be retrieved from the resulting value using "PyLong_AsVoidPtr()".

long PyLong_AsLong(PyObject *obj)

   Return a C "long" representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__int__()" method (if
   present) to convert it to a "PyLongObject".

   Raise "OverflowError" if the value of *obj* is out of range for a
   "long".

long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

   Return a C "long" representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__int__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "LONG_MAX" or less than
   "LONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

PY_LONG_LONG PyLong_AsLongLong(PyObject *obj)

   Return a C "long long" representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__int__()" method (if
   present) to convert it to a "PyLongObject".

   Raise "OverflowError" if the value of *obj* is out of range for a
   "long".

PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

   Return a C "long long" representation of *obj*.  If *obj* is not an
   instance of "PyLongObject", first call its "__int__()" method (if
   present) to convert it to a "PyLongObject".

   If the value of *obj* is greater than "PY_LLONG_MAX" or less than
   "PY_LLONG_MIN", set **overflow* to "1" or "-1", respectively, and
   return "-1"; otherwise, set **overflow* to "0".  If any other
   exception occurs set **overflow* to "0" and return "-1" as usual.

   New in version 3.2.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

   Return a C "Py_ssize_t" representation of *pylong*.  *pylong* must
   be an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a "Py_ssize_t".

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

   Return a C "unsigned long" representation of *pylong*.  *pylong*
   must be an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a "unsigned long".

size_t PyLong_AsSize_t(PyObject *pylong)

   Return a C "size_t" representation of *pylong*.  *pylong* must be
   an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a "size_t".

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)

   Return a C "unsigned PY_LONG_LONG" representation of *pylong*.
   *pylong* must be an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   an "unsigned PY_LONG_LONG".

   Changed in version 3.1: A negative *pylong* now raises
   "OverflowError", not "TypeError".

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)

   Return a C "unsigned long" representation of *obj*.  If *obj* is
   not an instance of "PyLongObject", first call its "__int__()"
   method (if present) to convert it to a "PyLongObject".

   If the value of *obj* is out of range for an "unsigned long",
   return the reduction of that value modulo "ULONG_MAX + 1".

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *obj)

   Return a C "unsigned long long" representation of *obj*.  If *obj*
   is not an instance of "PyLongObject", first call its "__int__()"
   method (if present) to convert it to a "PyLongObject".

   If the value of *obj* is out of range for an "unsigned long long",
   return the reduction of that value modulo "PY_ULLONG_MAX + 1".

double PyLong_AsDouble(PyObject *pylong)

   Return a C "double" representation of *pylong*.  *pylong* must be
   an instance of "PyLongObject".

   Raise "OverflowError" if the value of *pylong* is out of range for
   a "double".

void* PyLong_AsVoidPtr(PyObject *pylong)

   Convert a Python integer *pylong* to a C "void" pointer. If
   *pylong* cannot be converted, an "OverflowError" will be raised.
   This is only assured to produce a usable "void" pointer for values
   created with "PyLong_FromVoidPtr()".
