1 .. highlightlang:: c

     2 

     3 .. _longobjects:

     4 

     5 Long Integer Objects

     6 --------------------

     7 

     8 .. index:: object: long integer

     9 

    10 

    11 .. ctype:: PyLongObject

    12 

    13    This subtype of :ctype:`PyObject` represents a Python long integer object.

    14 

    15 

    16 .. cvar:: PyTypeObject PyLong_Type

    17 

    18    .. index:: single: LongType (in modules types)

    19 

    20    This instance of :ctype:`PyTypeObject` represents the Python long integer type.

    21    This is the same object as ``long`` and ``types.LongType``.

    22 

    23 

    24 .. cfunction:: int PyLong_Check(PyObject *p)

    25 

    26    Return true if its argument is a :ctype:`PyLongObject` or a subtype of

    27    :ctype:`PyLongObject`.

    28 

    29    .. versionchanged:: 2.2

    30       Allowed subtypes to be accepted.

    31 

    32 

    33 .. cfunction:: int PyLong_CheckExact(PyObject *p)

    34 

    35    Return true if its argument is a :ctype:`PyLongObject`, but not a subtype of

    36    :ctype:`PyLongObject`.

    37 

    38    .. versionadded:: 2.2

    39 

    40 

    41 .. cfunction:: PyObject* PyLong_FromLong(long v)

    42 

    43    Return a new :ctype:`PyLongObject` object from *v*, or *NULL* on failure.

    44 

    45 

    46 .. cfunction:: PyObject* PyLong_FromUnsignedLong(unsigned long v)

    47 

    48    Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long`, or

    49    *NULL* on failure.

    50 

    51 

    52 .. cfunction:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)

    53 

    54    Return a new :ctype:`PyLongObject` object from a C :ctype:`Py_ssize_t`, or

    55    *NULL* on failure.

    56 

    57    .. versionadded:: 2.5

    58 

    59 

    60 .. cfunction:: PyObject* PyLong_FromSize_t(size_t v)

    61 

    62    Return a new :ctype:`PyLongObject` object from a C :ctype:`size_t`, or

    63    *NULL* on failure.

    64 

    65    .. versionadded:: 2.5

    66 

    67 

    68 .. cfunction:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)

    69 

    70    Return a new :ctype:`PyLongObject` object from a C :ctype:`long long`, or *NULL*

    71    on failure.

    72 

    73 

    74 .. cfunction:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)

    75 

    76    Return a new :ctype:`PyLongObject` object from a C :ctype:`unsigned long long`,

    77    or *NULL* on failure.

    78 

    79 

    80 .. cfunction:: PyObject* PyLong_FromDouble(double v)

    81 

    82    Return a new :ctype:`PyLongObject` object from the integer part of *v*, or

    83    *NULL* on failure.

    84 

    85 

    86 .. cfunction:: PyObject* PyLong_FromString(char *str, char **pend, int base)

    87 

    88    Return a new :ctype:`PyLongObject` based on the string value in *str*, which is

    89    interpreted according to the radix in *base*.  If *pend* is non-*NULL*,

    90    ``*pend`` will point to the first character in *str* which follows the

    91    representation of the number.  If *base* is ``0``, the radix will be determined

    92    based on the leading characters of *str*: if *str* starts with ``'0x'`` or

    93    ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be

    94    used; otherwise radix 10 will be used.  If *base* is not ``0``, it must be

    95    between ``2`` and ``36``, inclusive.  Leading spaces are ignored.  If there are

    96    no digits, :exc:`ValueError` will be raised.

    97 

    98 

    99 .. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)

   100 

   101    Convert a sequence of Unicode digits to a Python long integer value.  The first

   102    parameter, *u*, points to the first character of the Unicode string, *length*

   103    gives the number of characters, and *base* is the radix for the conversion.  The

   104    radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`

   105    will be raised.

   106 

   107    .. versionadded:: 1.6

   108 

   109 

   110 .. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)

   111 

   112    Create a Python integer or long integer from the pointer *p*. The pointer value

   113    can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.

   114 

   115    .. versionadded:: 1.5.2

   116 

   117    .. versionchanged:: 2.5

   118       If the integer is larger than LONG_MAX, a positive long integer is returned.

   119 

   120 

   121 .. cfunction:: long PyLong_AsLong(PyObject *pylong)

   122 

   123    .. index::

   124       single: LONG_MAX

   125       single: OverflowError (built-in exception)

   126 

   127    Return a C :ctype:`long` representation of the contents of *pylong*.  If

   128    *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised

   129    and ``-1`` will be returned. 

   130 

   131 

   132 .. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)

   133 

   134    .. index::

   135       single: PY_SSIZE_T_MAX

   136       single: OverflowError (built-in exception)

   137 

   138    Return a C :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If

   139    *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised

   140    and ``-1`` will be returned.

   141 

   142    .. versionadded:: 2.5

   143 

   144 

   145 .. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)

   146 

   147    .. index::

   148       single: ULONG_MAX

   149       single: OverflowError (built-in exception)

   150 

   151    Return a C :ctype:`unsigned long` representation of the contents of *pylong*.

   152    If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is

   153    raised.

   154 

   155 

   156 .. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)

   157 

   158    Return a C :ctype:`long long` from a Python long integer.  If *pylong* cannot be

   159    represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.

   160 

   161    .. versionadded:: 2.2

   162 

   163 

   164 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)

   165 

   166    Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*

   167    cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`

   168    will be raised if the value is positive, or a :exc:`TypeError` will be raised if

   169    the value is negative.

   170 

   171    .. versionadded:: 2.2

   172 

   173 

   174 .. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)

   175 

   176    Return a C :ctype:`unsigned long` from a Python long integer, without checking

   177    for overflow.

   178 

   179    .. versionadded:: 2.3

   180 

   181 

   182 .. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)

   183 

   184    Return a C :ctype:`unsigned long long` from a Python long integer, without

   185    checking for overflow.

   186 

   187    .. versionadded:: 2.3

   188 

   189 

   190 .. cfunction:: double PyLong_AsDouble(PyObject *pylong)

   191 

   192    Return a C :ctype:`double` representation of the contents of *pylong*.  If

   193    *pylong* cannot be approximately represented as a :ctype:`double`, an

   194    :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.

   195 

   196 

   197 .. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)

   198 

   199    Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.

   200    If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This

   201    is only assured to produce a usable :ctype:`void` pointer for values created

   202    with :cfunc:`PyLong_FromVoidPtr`.

   203 

   204    .. versionadded:: 1.5.2

   205 

   206    .. versionchanged:: 2.5

   207       For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.

   208 

   209