Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _longobjects: |
| 4 | |
| 5 | Integer Objects |
| 6 | --------------- |
| 7 | |
| 8 | .. index:: object: long integer |
| 9 | object: integer |
| 10 | |
| 11 | All integers are implemented as "long" integer objects of arbitrary size. |
| 12 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 13 | .. c:type:: PyLongObject |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 14 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 15 | This subtype of :c:type:`PyObject` represents a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 16 | |
| 17 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 18 | .. c:var:: PyTypeObject PyLong_Type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 19 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 20 | This instance of :c:type:`PyTypeObject` represents the Python integer type. |
Georg Brandl | 2aff335 | 2010-10-17 10:59:41 +0000 | [diff] [blame] | 21 | This is the same object as :class:`int` in the Python layer. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 22 | |
| 23 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 24 | .. c:function:: int PyLong_Check(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 25 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 26 | Return true if its argument is a :c:type:`PyLongObject` or a subtype of |
| 27 | :c:type:`PyLongObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 28 | |
| 29 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 30 | .. c:function:: int PyLong_CheckExact(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 31 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 32 | Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of |
| 33 | :c:type:`PyLongObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 34 | |
| 35 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 36 | .. c:function:: PyObject* PyLong_FromLong(long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 37 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 38 | Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 39 | |
| 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 Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 47 | .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 48 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 49 | Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 50 | *NULL* on failure. |
| 51 | |
| 52 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 53 | .. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 54 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 55 | Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 56 | *NULL* on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 57 | |
| 58 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 59 | .. c:function:: PyObject* PyLong_FromSize_t(size_t v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 60 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 61 | Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 62 | *NULL* on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 63 | |
| 64 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 65 | .. c:function:: PyObject* PyLong_FromLongLong(PY_LONG_LONG v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 66 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 67 | Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL* |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 68 | on failure. |
| 69 | |
| 70 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 71 | .. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned PY_LONG_LONG v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 72 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 73 | Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 74 | or *NULL* on failure. |
| 75 | |
| 76 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 77 | .. c:function:: PyObject* PyLong_FromDouble(double v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 78 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 79 | Return a new :c:type:`PyLongObject` object from the integer part of *v*, or |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 80 | *NULL* on failure. |
| 81 | |
| 82 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 83 | .. c:function:: PyObject* PyLong_FromString(char *str, char **pend, int base) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 84 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 85 | Return a new :c:type:`PyLongObject` based on the string value in *str*, which |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 86 | is interpreted according to the radix in *base*. If *pend* is non-*NULL*, |
Ezio Melotti | ea30c6f | 2010-01-30 13:32:14 +0000 | [diff] [blame] | 87 | *\*pend* will point to the first character in *str* which follows the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 88 | 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 Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 97 | .. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 98 | |
| 99 | Convert a sequence of Unicode digits to a Python integer value. The Unicode |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 100 | string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal` |
| 101 | and then converted using :c:func:`PyLong_FromString`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 102 | |
| 103 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 104 | .. c:function:: PyObject* PyLong_FromVoidPtr(void *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 105 | |
| 106 | Create a Python integer from the pointer *p*. The pointer value can be |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 107 | retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 108 | |
| 109 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 110 | .. XXX alias PyLong_AS_LONG (for now) |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 111 | .. c:function:: long PyLong_AsLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 112 | |
| 113 | .. index:: |
| 114 | single: LONG_MAX |
| 115 | single: OverflowError (built-in exception) |
| 116 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 117 | Return a C :c:type:`long` representation of the contents of *pylong*. If |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 118 | *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 Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 122 | .. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 123 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 124 | Return a C :c:type:`long` representation of the contents of |
Mark Dickinson | 309aa2d | 2009-12-21 12:37:06 +0000 | [diff] [blame] | 125 | *pylong*. If *pylong* is greater than :const:`LONG_MAX` or less |
Ezio Melotti | ea30c6f | 2010-01-30 13:32:14 +0000 | [diff] [blame] | 126 | than :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, |
| 127 | respectively, and return ``-1``; otherwise, set *\*overflow* to |
Mark Dickinson | 309aa2d | 2009-12-21 12:37:06 +0000 | [diff] [blame] | 128 | ``0``. If any other exception occurs (for example a TypeError or |
Ezio Melotti | ea30c6f | 2010-01-30 13:32:14 +0000 | [diff] [blame] | 129 | MemoryError), then ``-1`` will be returned and *\*overflow* will |
Mark Dickinson | 309aa2d | 2009-12-21 12:37:06 +0000 | [diff] [blame] | 130 | be ``0``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 131 | |
| 132 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 133 | .. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow) |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 134 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 135 | Return a C :c:type:`long long` representation of the contents of |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 136 | *pylong*. If *pylong* is greater than :const:`PY_LLONG_MAX` or less |
Ezio Melotti | ea30c6f | 2010-01-30 13:32:14 +0000 | [diff] [blame] | 137 | than :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, |
| 138 | respectively, and return ``-1``; otherwise, set *\*overflow* to |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 139 | ``0``. If any other exception occurs (for example a TypeError or |
Ezio Melotti | ea30c6f | 2010-01-30 13:32:14 +0000 | [diff] [blame] | 140 | MemoryError), then ``-1`` will be returned and *\*overflow* will |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 141 | be ``0``. |
| 142 | |
| 143 | .. versionadded:: 3.2 |
| 144 | |
| 145 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 146 | .. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 147 | |
| 148 | .. index:: |
| 149 | single: PY_SSIZE_T_MAX |
| 150 | single: OverflowError (built-in exception) |
| 151 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 152 | Return a C :c:type:`Py_ssize_t` representation of the contents of *pylong*. |
Georg Brandl | 5081f7e | 2009-03-31 15:49:02 +0000 | [diff] [blame] | 153 | If *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` |
| 154 | is raised and ``-1`` will be returned. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 155 | |
| 156 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 157 | .. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 158 | |
| 159 | .. index:: |
| 160 | single: ULONG_MAX |
| 161 | single: OverflowError (built-in exception) |
| 162 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 163 | Return a C :c:type:`unsigned long` representation of the contents of *pylong*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 164 | If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is |
| 165 | raised. |
| 166 | |
| 167 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 168 | .. c:function:: size_t PyLong_AsSize_t(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 169 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 170 | 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 Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 172 | :exc:`OverflowError` is raised. |
| 173 | |
| 174 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 175 | .. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 176 | |
Mark Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 177 | .. index:: |
| 178 | single: OverflowError (built-in exception) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 179 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 180 | 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 Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 182 | :exc:`OverflowError` is raised and ``-1`` is returned. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 183 | |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 184 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 185 | .. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 186 | |
Mark Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 187 | .. index:: |
| 188 | single: OverflowError (built-in exception) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 189 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 190 | 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 Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 192 | an :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is |
| 193 | returned. |
| 194 | |
| 195 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 196 | A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`. |
| 197 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 198 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 199 | .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 200 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 201 | Return a C :c:type:`unsigned long` from a Python integer, without checking for |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 202 | overflow. |
| 203 | |
| 204 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 205 | .. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 206 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 207 | Return a C :c:type:`unsigned long long` from a Python integer, without |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 208 | checking for overflow. |
| 209 | |
| 210 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 211 | .. c:function:: double PyLong_AsDouble(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 212 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 213 | 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 Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 215 | :exc:`OverflowError` exception is raised and ``-1.0`` will be returned. |
| 216 | |
| 217 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 218 | .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 219 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 220 | Convert a Python integer *pylong* to a C :c:type:`void` pointer. |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 221 | If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 222 | is only assured to produce a usable :c:type:`void` pointer for values created |
| 223 | with :c:func:`PyLong_FromVoidPtr`. |