
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()``.

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 *pylong)

   Return a C ``long`` representation of the contents of *pylong*.  If
   *pylong* is greater than ``LONG_MAX``, raise an ``OverflowError``,
   and return -1. Convert non-long objects automatically to long
   first, and return -1 if that raises exceptions.

long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)

   Return a C ``long`` representation of the contents of *pylong*.  If
   *pylong* 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 (for example a TypeError or MemoryError), then
   ``-1`` will be returned and **overflow* will be ``0``.

PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)

   Return a C ``long long`` representation of the contents of
   *pylong*.  If *pylong* 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 (for example a TypeError or
   MemoryError), then ``-1`` will be returned and **overflow* will be
   ``0``.

   New in version 3.2.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

   Return a C ``Py_ssize_t`` representation of the contents of
   *pylong*. If *pylong* is greater than ``PY_SSIZE_T_MAX``, an
   ``OverflowError`` is raised and ``-1`` will be returned.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

   Return a C ``unsigned long`` representation of the contents of
   *pylong*. If *pylong* is greater than ``ULONG_MAX``, an
   ``OverflowError`` is raised.

size_t PyLong_AsSize_t(PyObject *pylong)

   Return a ``size_t`` representation of the contents of *pylong*.  If
   *pylong* is greater than the maximum value for a ``size_t``, an
   ``OverflowError`` is raised.

PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)

   Return a C ``long long`` from a Python integer.  If *pylong* cannot
   be represented as a ``long long``, an ``OverflowError`` is raised
   and ``-1`` is returned.

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)

   Return a C ``unsigned long long`` from a Python integer. If
   *pylong* cannot be represented as an ``unsigned long long``, an
   ``OverflowError`` is raised and ``(unsigned long long)-1`` is
   returned.

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

unsigned long PyLong_AsUnsignedLongMask(PyObject *io)

   Return a C ``unsigned long`` from a Python integer, without
   checking for overflow.

unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)

   Return a C ``unsigned long long`` from a Python integer, without
   checking for overflow.

double PyLong_AsDouble(PyObject *pylong)

   Return a C ``double`` representation of the contents of *pylong*.
   If *pylong* cannot be approximately represented as a ``double``, an
   ``OverflowError`` exception is raised and ``-1.0`` will be
   returned.

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()``.
