1.. highlight:: c
2
3.. _longobjects:
4
5Integer Objects
6---------------
7
8.. index:: object: long integer
9           object: integer
10
11All integers are implemented as "long" integer objects of arbitrary size.
12
13On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be
14distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
15
16.. c:type:: PyLongObject
17
18   This subtype of :c:type:`PyObject` represents a Python integer object.
19
20
21.. c:var:: PyTypeObject PyLong_Type
22
23   This instance of :c:type:`PyTypeObject` represents the Python integer type.
24   This is the same object as :class:`int` in the Python layer.
25
26
27.. c:function:: int PyLong_Check(PyObject *p)
28
29   Return true if its argument is a :c:type:`PyLongObject` or a subtype of
30   :c:type:`PyLongObject`.
31
32
33.. c:function:: int PyLong_CheckExact(PyObject *p)
34
35   Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
36   :c:type:`PyLongObject`.
37
38
39.. c:function:: PyObject* PyLong_FromLong(long v)
40
41   Return a new :c:type:`PyLongObject` object from *v*, or ``NULL`` on failure.
42
43   The current implementation keeps an array of integer objects for all integers
44   between ``-5`` and ``256``, when you create an int in that range you actually
45   just get back a reference to the existing object.
46
47
48.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
49
50   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
51   ``NULL`` on failure.
52
53
54.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
55
56   Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
57   ``NULL`` on failure.
58
59
60.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
61
62   Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
63   ``NULL`` on failure.
64
65
66.. c:function:: PyObject* PyLong_FromLongLong(long long v)
67
68   Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or ``NULL``
69   on failure.
70
71
72.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
73
74   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
75   or ``NULL`` on failure.
76
77
78.. c:function:: PyObject* PyLong_FromDouble(double v)
79
80   Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
81   ``NULL`` on failure.
82
83
84.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
85
86   Return a new :c:type:`PyLongObject` based on the string value in *str*, which
87   is interpreted according to the radix in *base*.  If *pend* is non-``NULL``,
88   *\*pend* will point to the first character in *str* which follows the
89   representation of the number.  If *base* is ``0``, *str* is interpreted using
90   the :ref:`integers` definition; in this case, leading zeros in a
91   non-zero decimal number raises a :exc:`ValueError`. If *base* is not ``0``,
92   it must be between ``2`` and ``36``, inclusive.  Leading spaces and single
93   underscores after a base specifier and between digits are ignored.  If there
94   are no digits, :exc:`ValueError` will be raised.
95
96
97.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
98
99   Convert a sequence of Unicode digits to a Python integer value.
100
101   .. deprecated-removed:: 3.3 3.10
102      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
103      :c:func:`PyLong_FromUnicodeObject`.
104
105
106.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
107
108   Convert a sequence of Unicode digits in the string *u* to a Python integer
109   value.
110
111   .. versionadded:: 3.3
112
113
114.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
115
116   Create a Python integer from the pointer *p*. The pointer value can be
117   retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
118
119
120.. XXX alias PyLong_AS_LONG (for now)
121.. c:function:: long PyLong_AsLong(PyObject *obj)
122
123   .. index::
124      single: LONG_MAX
125      single: OverflowError (built-in exception)
126
127   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
128   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
129   :meth:`__int__` method (if present) to convert it to a
130   :c:type:`PyLongObject`.
131
132   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
133   :c:type:`long`.
134
135   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
136
137   .. versionchanged:: 3.8
138      Use :meth:`__index__` if available.
139
140   .. deprecated:: 3.8
141      Using :meth:`__int__` is deprecated.
142
143
144.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
145
146   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
147   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
148   :meth:`__int__` method (if present) to convert it to a
149   :c:type:`PyLongObject`.
150
151   If the value of *obj* is greater than :const:`LONG_MAX` or less than
152   :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
153   return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other exception
154   occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
155
156   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
157
158   .. versionchanged:: 3.8
159      Use :meth:`__index__` if available.
160
161   .. deprecated:: 3.8
162      Using :meth:`__int__` is deprecated.
163
164
165.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
166
167   .. index::
168      single: OverflowError (built-in exception)
169
170   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
171   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
172   :meth:`__int__` method (if present) to convert it to a
173   :c:type:`PyLongObject`.
174
175   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
176   :c:type:`long long`.
177
178   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
179
180   .. versionchanged:: 3.8
181      Use :meth:`__index__` if available.
182
183   .. deprecated:: 3.8
184      Using :meth:`__int__` is deprecated.
185
186
187.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
188
189   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
190   instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or
191   :meth:`__int__` method (if present) to convert it to a
192   :c:type:`PyLongObject`.
193
194   If the value of *obj* is greater than :const:`LLONG_MAX` or less than
195   :const:`LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
196   and return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other
197   exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
198
199   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
200
201   .. versionadded:: 3.2
202
203   .. versionchanged:: 3.8
204      Use :meth:`__index__` if available.
205
206   .. deprecated:: 3.8
207      Using :meth:`__int__` is deprecated.
208
209
210.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
211
212   .. index::
213      single: PY_SSIZE_T_MAX
214      single: OverflowError (built-in exception)
215
216   Return a C :c:type:`Py_ssize_t` representation of *pylong*.  *pylong* must
217   be an instance of :c:type:`PyLongObject`.
218
219   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
220   :c:type:`Py_ssize_t`.
221
222   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
223
224
225.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
226
227   .. index::
228      single: ULONG_MAX
229      single: OverflowError (built-in exception)
230
231   Return a C :c:type:`unsigned long` representation of *pylong*.  *pylong*
232   must be an instance of :c:type:`PyLongObject`.
233
234   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
235   :c:type:`unsigned long`.
236
237   Returns ``(unsigned long)-1`` on error.
238   Use :c:func:`PyErr_Occurred` to disambiguate.
239
240
241.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
242
243   .. index::
244      single: SIZE_MAX
245      single: OverflowError (built-in exception)
246
247   Return a C :c:type:`size_t` representation of *pylong*.  *pylong* must be
248   an instance of :c:type:`PyLongObject`.
249
250   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
251   :c:type:`size_t`.
252
253   Returns ``(size_t)-1`` on error.
254   Use :c:func:`PyErr_Occurred` to disambiguate.
255
256
257.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
258
259   .. index::
260      single: OverflowError (built-in exception)
261
262   Return a C :c:type:`unsigned long long` representation of *pylong*.  *pylong*
263   must be an instance of :c:type:`PyLongObject`.
264
265   Raise :exc:`OverflowError` if the value of *pylong* is out of range for an
266   :c:type:`unsigned long long`.
267
268   Returns ``(unsigned long long)-1`` on error.
269   Use :c:func:`PyErr_Occurred` to disambiguate.
270
271   .. versionchanged:: 3.1
272      A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
273
274
275.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
276
277   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
278   is not an instance of :c:type:`PyLongObject`, first call its
279   :meth:`__index__` or :meth:`__int__` method (if present) to convert
280   it to a :c:type:`PyLongObject`.
281
282   If the value of *obj* is out of range for an :c:type:`unsigned long`,
283   return the reduction of that value modulo ``ULONG_MAX + 1``.
284
285   Returns ``(unsigned long)-1`` on error.  Use :c:func:`PyErr_Occurred` to
286   disambiguate.
287
288   .. versionchanged:: 3.8
289      Use :meth:`__index__` if available.
290
291   .. deprecated:: 3.8
292      Using :meth:`__int__` is deprecated.
293
294
295.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
296
297   Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
298   is not an instance of :c:type:`PyLongObject`, first call its
299   :meth:`__index__` or :meth:`__int__` method (if present) to convert
300   it to a :c:type:`PyLongObject`.
301
302   If the value of *obj* is out of range for an :c:type:`unsigned long long`,
303   return the reduction of that value modulo ``ULLONG_MAX + 1``.
304
305   Returns ``(unsigned long long)-1`` on error.  Use :c:func:`PyErr_Occurred`
306   to disambiguate.
307
308   .. versionchanged:: 3.8
309      Use :meth:`__index__` if available.
310
311   .. deprecated:: 3.8
312      Using :meth:`__int__` is deprecated.
313
314
315.. c:function:: double PyLong_AsDouble(PyObject *pylong)
316
317   Return a C :c:type:`double` representation of *pylong*.  *pylong* must be
318   an instance of :c:type:`PyLongObject`.
319
320   Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
321   :c:type:`double`.
322
323   Returns ``-1.0`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
324
325
326.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
327
328   Convert a Python integer *pylong* to a C :c:type:`void` pointer.
329   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
330   is only assured to produce a usable :c:type:`void` pointer for values created
331   with :c:func:`PyLong_FromVoidPtr`.
332
333   Returns ``NULL`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
334