/Doc/c-api/long.rst

  1.. highlightlang:: c
  2
  3.. _longobjects:
  4
  5Long 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.6
 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.6
 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   .. versionchanged:: 2.5
110      This function used an :ctype:`int` for *length*. This might require
111      changes in your code for properly supporting 64-bit systems.
112
113
114.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
115
116   Create a Python integer or long integer from the pointer *p*. The pointer value
117   can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.
118
119   .. versionadded:: 1.5.2
120
121   .. versionchanged:: 2.5
122      If the integer is larger than LONG_MAX, a positive long integer is returned.
123
124
125.. cfunction:: long PyLong_AsLong(PyObject *pylong)
126
127   .. index::
128      single: LONG_MAX
129      single: OverflowError (built-in exception)
130
131   Return a C :ctype:`long` representation of the contents of *pylong*.  If
132   *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised
133   and ``-1`` will be returned.
134
135
136.. cfunction:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
137
138   .. index::
139      single: PY_SSIZE_T_MAX
140      single: OverflowError (built-in exception)
141
142   Return a C :ctype:`Py_ssize_t` representation of the contents of *pylong*.  If
143   *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised
144   and ``-1`` will be returned.
145
146   .. versionadded:: 2.6
147
148
149.. cfunction:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
150
151   .. index::
152      single: ULONG_MAX
153      single: OverflowError (built-in exception)
154
155   Return a C :ctype:`unsigned long` representation of the contents of *pylong*.
156   If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
157   raised.
158
159
160.. cfunction:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
161
162   Return a C :ctype:`long long` from a Python long integer.  If *pylong* cannot be
163   represented as a :ctype:`long long`, an :exc:`OverflowError` will be raised.
164
165   .. versionadded:: 2.2
166
167
168.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
169
170   Return a C :ctype:`unsigned long long` from a Python long integer. If *pylong*
171   cannot be represented as an :ctype:`unsigned long long`, an :exc:`OverflowError`
172   will be raised if the value is positive, or a :exc:`TypeError` will be raised if
173   the value is negative.
174
175   .. versionadded:: 2.2
176
177
178.. cfunction:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
179
180   Return a C :ctype:`unsigned long` from a Python long integer, without checking
181   for overflow.
182
183   .. versionadded:: 2.3
184
185
186.. cfunction:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
187
188   Return a C :ctype:`unsigned long long` from a Python long integer, without
189   checking for overflow.
190
191   .. versionadded:: 2.3
192
193
194.. cfunction:: double PyLong_AsDouble(PyObject *pylong)
195
196   Return a C :ctype:`double` representation of the contents of *pylong*.  If
197   *pylong* cannot be approximately represented as a :ctype:`double`, an
198   :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
199
200
201.. cfunction:: void* PyLong_AsVoidPtr(PyObject *pylong)
202
203   Convert a Python integer or long integer *pylong* to a C :ctype:`void` pointer.
204   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
205   is only assured to produce a usable :ctype:`void` pointer for values created
206   with :cfunc:`PyLong_FromVoidPtr`.
207
208   .. versionadded:: 1.5.2
209
210   .. versionchanged:: 2.5
211      For values outside 0..LONG_MAX, both signed and unsigned integers are accepted.
212
213