blob: 6ae1fb69ea5746308c22c6c0fd3f3b766750012b [file] [log] [blame]
Georg Brandl54a3faa2008-01-20 09:30:57 +00001.. highlightlang:: 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
Georg Brandl60203b42010-10-06 10:11:56 +000013.. c:type:: PyLongObject
Georg Brandl54a3faa2008-01-20 09:30:57 +000014
Georg Brandl60203b42010-10-06 10:11:56 +000015 This subtype of :c:type:`PyObject` represents a Python integer object.
Georg Brandl54a3faa2008-01-20 09:30:57 +000016
17
Georg Brandl60203b42010-10-06 10:11:56 +000018.. c:var:: PyTypeObject PyLong_Type
Georg Brandl54a3faa2008-01-20 09:30:57 +000019
Georg Brandl60203b42010-10-06 10:11:56 +000020 This instance of :c:type:`PyTypeObject` represents the Python integer type.
Georg Brandl54a3faa2008-01-20 09:30:57 +000021 This is the same object as ``int``.
22
23
Georg Brandl60203b42010-10-06 10:11:56 +000024.. c:function:: int PyLong_Check(PyObject *p)
Georg Brandl54a3faa2008-01-20 09:30:57 +000025
Georg Brandl60203b42010-10-06 10:11:56 +000026 Return true if its argument is a :c:type:`PyLongObject` or a subtype of
27 :c:type:`PyLongObject`.
Georg Brandl54a3faa2008-01-20 09:30:57 +000028
29
Georg Brandl60203b42010-10-06 10:11:56 +000030.. c:function:: int PyLong_CheckExact(PyObject *p)
Georg Brandl54a3faa2008-01-20 09:30:57 +000031
Georg Brandl60203b42010-10-06 10:11:56 +000032 Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
33 :c:type:`PyLongObject`.
Georg Brandl54a3faa2008-01-20 09:30:57 +000034
35
Georg Brandl60203b42010-10-06 10:11:56 +000036.. c:function:: PyObject* PyLong_FromLong(long v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000037
Georg Brandl60203b42010-10-06 10:11:56 +000038 Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
Georg Brandl54a3faa2008-01-20 09:30:57 +000039
40 The current implementation keeps an array of integer objects for all integers
41 between ``-5`` and ``256``, when you create an int in that range you actually
42 just get back a reference to the existing object. So it should be possible to
43 change the value of ``1``. I suspect the behaviour of Python in this case is
44 undefined. :-)
45
46
Georg Brandl60203b42010-10-06 10:11:56 +000047.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000048
Georg Brandl60203b42010-10-06 10:11:56 +000049 Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
Georg Brandl54a3faa2008-01-20 09:30:57 +000050 *NULL* on failure.
51
52
Georg Brandl60203b42010-10-06 10:11:56 +000053.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000054
Georg Brandl60203b42010-10-06 10:11:56 +000055 Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
Christian Heimes81ee3ef2008-05-04 22:42:01 +000056 *NULL* on failure.
Georg Brandl54a3faa2008-01-20 09:30:57 +000057
58
Georg Brandl60203b42010-10-06 10:11:56 +000059.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000060
Georg Brandl60203b42010-10-06 10:11:56 +000061 Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
Christian Heimes81ee3ef2008-05-04 22:42:01 +000062 *NULL* on failure.
Georg Brandl54a3faa2008-01-20 09:30:57 +000063
64
Georg Brandl60203b42010-10-06 10:11:56 +000065.. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000066
Georg Brandl60203b42010-10-06 10:11:56 +000067 Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
Georg Brandl54a3faa2008-01-20 09:30:57 +000068 on failure.
69
70
Georg Brandl60203b42010-10-06 10:11:56 +000071.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000072
Georg Brandl60203b42010-10-06 10:11:56 +000073 Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
Georg Brandl54a3faa2008-01-20 09:30:57 +000074 or *NULL* on failure.
75
76
Georg Brandl60203b42010-10-06 10:11:56 +000077.. c:function:: PyObject* PyLong_FromDouble(double v)
Georg Brandl54a3faa2008-01-20 09:30:57 +000078
Georg Brandl60203b42010-10-06 10:11:56 +000079 Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
Georg Brandl54a3faa2008-01-20 09:30:57 +000080 *NULL* on failure.
81
82
Georg Brandl60203b42010-10-06 10:11:56 +000083.. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base)
Georg Brandl54a3faa2008-01-20 09:30:57 +000084
Georg Brandl60203b42010-10-06 10:11:56 +000085 Return a new :c:type:`PyLongObject` based on the string value in *str*, which
Georg Brandl54a3faa2008-01-20 09:30:57 +000086 is interpreted according to the radix in *base*. If *pend* is non-*NULL*,
Ezio Melottiea30c6f2010-01-30 13:32:14 +000087 *\*pend* will point to the first character in *str* which follows the
Georg Brandl54a3faa2008-01-20 09:30:57 +000088 representation of the number. If *base* is ``0``, the radix will be
89 determined based on the leading characters of *str*: if *str* starts with
90 ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0o'`` or
91 ``'0O'``, radix 8 will be used; if *str* starts with ``'0b'`` or ``'0B'``,
92 radix 2 will be used; otherwise radix 10 will be used. If *base* is not
93 ``0``, it must be between ``2`` and ``36``, inclusive. Leading spaces are
94 ignored. If there are no digits, :exc:`ValueError` will be raised.
95
96
Georg Brandl60203b42010-10-06 10:11:56 +000097.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
Georg Brandl54a3faa2008-01-20 09:30:57 +000098
99 Convert a sequence of Unicode digits to a Python integer value. The Unicode
Georg Brandl60203b42010-10-06 10:11:56 +0000100 string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
101 and then converted using :c:func:`PyLong_FromString`.
Georg Brandl54a3faa2008-01-20 09:30:57 +0000102
103
Georg Brandl60203b42010-10-06 10:11:56 +0000104.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000105
106 Create a Python integer from the pointer *p*. The pointer value can be
Georg Brandl60203b42010-10-06 10:11:56 +0000107 retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
Georg Brandl54a3faa2008-01-20 09:30:57 +0000108
109
Georg Brandl48310cd2009-01-03 21:18:54 +0000110.. XXX alias PyLong_AS_LONG (for now)
Georg Brandl60203b42010-10-06 10:11:56 +0000111.. c:function:: long PyLong_AsLong(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000112
113 .. index::
114 single: LONG_MAX
115 single: OverflowError (built-in exception)
116
Georg Brandl60203b42010-10-06 10:11:56 +0000117 Return a C :c:type:`long` representation of the contents of *pylong*. If
Georg Brandl54a3faa2008-01-20 09:30:57 +0000118 *pylong* is greater than :const:`LONG_MAX`, raise an :exc:`OverflowError`,
119 and return -1. Convert non-long objects automatically to long first,
120 and return -1 if that raises exceptions.
121
Georg Brandl60203b42010-10-06 10:11:56 +0000122.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000123
Georg Brandl60203b42010-10-06 10:11:56 +0000124 Return a C :c:type:`long` representation of the contents of
Mark Dickinson309aa2d2009-12-21 12:37:06 +0000125 *pylong*. If *pylong* is greater than :const:`LONG_MAX` or less
Ezio Melottiea30c6f2010-01-30 13:32:14 +0000126 than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
127 respectively, and return ``-1``; otherwise, set *\*overflow* to
Mark Dickinson309aa2d2009-12-21 12:37:06 +0000128 ``0``. If any other exception occurs (for example a TypeError or
Ezio Melottiea30c6f2010-01-30 13:32:14 +0000129 MemoryError), then ``-1`` will be returned and *\*overflow* will
Mark Dickinson309aa2d2009-12-21 12:37:06 +0000130 be ``0``.
Georg Brandl54a3faa2008-01-20 09:30:57 +0000131
132
Georg Brandl60203b42010-10-06 10:11:56 +0000133.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow)
Mark Dickinson93f562c2010-01-30 10:30:15 +0000134
Georg Brandl60203b42010-10-06 10:11:56 +0000135 Return a C :c:type:`long long` representation of the contents of
Mark Dickinson93f562c2010-01-30 10:30:15 +0000136 *pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less
Ezio Melottiea30c6f2010-01-30 13:32:14 +0000137 than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``,
138 respectively, and return ``-1``; otherwise, set *\*overflow* to
Mark Dickinson93f562c2010-01-30 10:30:15 +0000139 ``0``. If any other exception occurs (for example a TypeError or
Ezio Melottiea30c6f2010-01-30 13:32:14 +0000140 MemoryError), then ``-1`` will be returned and *\*overflow* will
Mark Dickinson93f562c2010-01-30 10:30:15 +0000141 be ``0``.
142
143 .. versionadded:: 3.2
144
145
Georg Brandl60203b42010-10-06 10:11:56 +0000146.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000147
148 .. index::
149 single: PY_SSIZE_T_MAX
150 single: OverflowError (built-in exception)
151
Georg Brandl60203b42010-10-06 10:11:56 +0000152 Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*.
Georg Brandl5081f7e2009-03-31 15:49:02 +0000153 If *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError`
154 is raised and ``-1`` will be returned.
Christian Heimes81ee3ef2008-05-04 22:42:01 +0000155
156
Georg Brandl60203b42010-10-06 10:11:56 +0000157.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000158
159 .. index::
160 single: ULONG_MAX
161 single: OverflowError (built-in exception)
162
Georg Brandl60203b42010-10-06 10:11:56 +0000163 Return a C :c:type:`unsigned long` representation of the contents of *pylong*.
Georg Brandl54a3faa2008-01-20 09:30:57 +0000164 If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is
165 raised.
166
167
Georg Brandl60203b42010-10-06 10:11:56 +0000168.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000169
Georg Brandl60203b42010-10-06 10:11:56 +0000170 Return a :c:type:`size_t` representation of the contents of *pylong*. If
171 *pylong* is greater than the maximum value for a :c:type:`size_t`, an
Georg Brandl54a3faa2008-01-20 09:30:57 +0000172 :exc:`OverflowError` is raised.
173
174
Georg Brandl60203b42010-10-06 10:11:56 +0000175.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000176
Mark Dickinson21776072009-02-10 16:13:25 +0000177 .. index::
178 single: OverflowError (built-in exception)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000179
Georg Brandl60203b42010-10-06 10:11:56 +0000180 Return a C :c:type:`long long` from a Python integer. If *pylong*
181 cannot be represented as a :c:type:`long long`, an
Mark Dickinson21776072009-02-10 16:13:25 +0000182 :exc:`OverflowError` is raised and ``-1`` is returned.
Georg Brandl54a3faa2008-01-20 09:30:57 +0000183
Georg Brandl67b21b72010-08-17 15:07:14 +0000184
Georg Brandl60203b42010-10-06 10:11:56 +0000185.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000186
Mark Dickinson21776072009-02-10 16:13:25 +0000187 .. index::
188 single: OverflowError (built-in exception)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000189
Georg Brandl60203b42010-10-06 10:11:56 +0000190 Return a C :c:type:`unsigned long long` from a Python integer. If
191 *pylong* cannot be represented as an :c:type:`unsigned long long`,
Mark Dickinson21776072009-02-10 16:13:25 +0000192 an :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is
193 returned.
194
195 .. versionchanged:: 3.1
Georg Brandl67b21b72010-08-17 15:07:14 +0000196 A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
197
Georg Brandl54a3faa2008-01-20 09:30:57 +0000198
Georg Brandl60203b42010-10-06 10:11:56 +0000199.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000200
Georg Brandl60203b42010-10-06 10:11:56 +0000201 Return a C :c:type:`unsigned long` from a Python integer, without checking for
Georg Brandl54a3faa2008-01-20 09:30:57 +0000202 overflow.
203
204
Georg Brandl60203b42010-10-06 10:11:56 +0000205.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000206
Georg Brandl60203b42010-10-06 10:11:56 +0000207 Return a C :c:type:`unsigned long long` from a Python integer, without
Georg Brandl54a3faa2008-01-20 09:30:57 +0000208 checking for overflow.
209
210
Georg Brandl60203b42010-10-06 10:11:56 +0000211.. c:function:: double PyLong_AsDouble(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000212
Georg Brandl60203b42010-10-06 10:11:56 +0000213 Return a C :c:type:`double` representation of the contents of *pylong*. If
214 *pylong* cannot be approximately represented as a :c:type:`double`, an
Georg Brandl54a3faa2008-01-20 09:30:57 +0000215 :exc:`OverflowError` exception is raised and ``-1.0`` will be returned.
216
217
Georg Brandl60203b42010-10-06 10:11:56 +0000218.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
Georg Brandl54a3faa2008-01-20 09:30:57 +0000219
Georg Brandl60203b42010-10-06 10:11:56 +0000220 Convert a Python integer *pylong* to a C :c:type:`void` pointer.
Christian Heimesc3f30c42008-02-22 16:37:40 +0000221 If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This
Georg Brandl60203b42010-10-06 10:11:56 +0000222 is only assured to produce a usable :c:type:`void` pointer for values created
223 with :c:func:`PyLong_FromVoidPtr`.