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 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 13 | On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be |
| 14 | distinguished from a number. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 15 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 16 | .. c:type:: PyLongObject |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 17 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 18 | This subtype of :c:type:`PyObject` represents a Python integer object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 19 | |
| 20 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 21 | .. c:var:: PyTypeObject PyLong_Type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 22 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 23 | This instance of :c:type:`PyTypeObject` represents the Python integer type. |
Georg Brandl | 2aff335 | 2010-10-17 10:59:41 +0000 | [diff] [blame] | 24 | This is the same object as :class:`int` in the Python layer. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 25 | |
| 26 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 27 | .. c:function:: int PyLong_Check(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 28 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 29 | Return true if its argument is a :c:type:`PyLongObject` or a subtype of |
| 30 | :c:type:`PyLongObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 31 | |
| 32 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 33 | .. c:function:: int PyLong_CheckExact(PyObject *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 34 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 35 | Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of |
| 36 | :c:type:`PyLongObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 37 | |
| 38 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 39 | .. c:function:: PyObject* PyLong_FromLong(long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 40 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 41 | 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] | 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. So it should be possible to |
| 46 | change the value of ``1``. I suspect the behaviour of Python in this case is |
| 47 | undefined. :-) |
| 48 | |
| 49 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 50 | .. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 51 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 52 | 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] | 53 | *NULL* on failure. |
| 54 | |
| 55 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 56 | .. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 57 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 58 | 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] | 59 | *NULL* on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 60 | |
| 61 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 62 | .. c:function:: PyObject* PyLong_FromSize_t(size_t v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 63 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 64 | 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] | 65 | *NULL* on failure. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 66 | |
| 67 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 68 | .. c:function:: PyObject* PyLong_FromLongLong(long long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 69 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 70 | 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] | 71 | on failure. |
| 72 | |
| 73 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 74 | .. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 75 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 76 | 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] | 77 | or *NULL* on failure. |
| 78 | |
| 79 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 80 | .. c:function:: PyObject* PyLong_FromDouble(double v) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 81 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 82 | 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] | 83 | *NULL* on failure. |
| 84 | |
| 85 | |
Serhiy Storchaka | c679227 | 2013-10-19 21:03:34 +0300 | [diff] [blame] | 86 | .. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 88 | 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] | 89 | 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] | 90 | *\*pend* will point to the first character in *str* which follows the |
csabella | 26896f2 | 2017-04-23 23:54:08 -0400 | [diff] [blame] | 91 | representation of the number. If *base* is ``0``, *str* is interpreted using |
| 92 | the :ref:`integers` definition; in this case, leading zeros in a |
| 93 | non-zero decimal number raises a :exc:`ValueError`. If *base* is not ``0``, |
| 94 | it must be between ``2`` and ``36``, inclusive. Leading spaces and single |
| 95 | underscores after a base specifier and between digits are ignored. If there |
| 96 | are no digits, :exc:`ValueError` will be raised. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 97 | |
| 98 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 99 | .. 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] | 100 | |
| 101 | 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] | 102 | string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal` |
| 103 | and then converted using :c:func:`PyLong_FromString`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 104 | |
Georg Brandl | db6c7f5 | 2011-10-07 11:19:11 +0200 | [diff] [blame] | 105 | .. deprecated-removed:: 3.3 4.0 |
| 106 | Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using |
| 107 | :c:func:`PyLong_FromUnicodeObject`. |
| 108 | |
| 109 | |
| 110 | .. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base) |
| 111 | |
| 112 | Convert a sequence of Unicode digits in the string *u* to a Python integer |
| 113 | value. The Unicode string is first encoded to a byte string using |
| 114 | :c:func:`PyUnicode_EncodeDecimal` and then converted using |
| 115 | :c:func:`PyLong_FromString`. |
| 116 | |
| 117 | .. versionadded:: 3.3 |
| 118 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 119 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 120 | .. c:function:: PyObject* PyLong_FromVoidPtr(void *p) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 121 | |
| 122 | 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] | 123 | retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 124 | |
| 125 | |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 126 | .. XXX alias PyLong_AS_LONG (for now) |
Mark Dickinson | 0a22924 | 2012-06-23 10:49:12 +0100 | [diff] [blame] | 127 | .. c:function:: long PyLong_AsLong(PyObject *obj) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 128 | |
| 129 | .. index:: |
| 130 | single: LONG_MAX |
| 131 | single: OverflowError (built-in exception) |
| 132 | |
Mark Dickinson | 0a22924 | 2012-06-23 10:49:12 +0100 | [diff] [blame] | 133 | Return a C :c:type:`long` representation of *obj*. If *obj* is not an |
| 134 | instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method |
| 135 | (if present) to convert it to a :c:type:`PyLongObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 136 | |
Mark Dickinson | 0a22924 | 2012-06-23 10:49:12 +0100 | [diff] [blame] | 137 | Raise :exc:`OverflowError` if the value of *obj* is out of range for a |
| 138 | :c:type:`long`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 139 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 140 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 141 | |
Mark Dickinson | f0acfee | 2012-06-23 11:14:22 +0100 | [diff] [blame] | 142 | |
Mark Dickinson | 0a22924 | 2012-06-23 10:49:12 +0100 | [diff] [blame] | 143 | .. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow) |
| 144 | |
| 145 | Return a C :c:type:`long` representation of *obj*. If *obj* is not an |
| 146 | instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method |
| 147 | (if present) to convert it to a :c:type:`PyLongObject`. |
| 148 | |
| 149 | If the value of *obj* is greater than :const:`LONG_MAX` or less than |
| 150 | :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and |
| 151 | return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception |
| 152 | occurs set *\*overflow* to ``0`` and return ``-1`` as usual. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 153 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 154 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 155 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 156 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 157 | .. c:function:: long long PyLong_AsLongLong(PyObject *obj) |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 158 | |
Mark Dickinson | f0acfee | 2012-06-23 11:14:22 +0100 | [diff] [blame] | 159 | .. index:: |
| 160 | single: OverflowError (built-in exception) |
| 161 | |
| 162 | Return a C :c:type:`long long` representation of *obj*. If *obj* is not an |
| 163 | instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method |
| 164 | (if present) to convert it to a :c:type:`PyLongObject`. |
| 165 | |
| 166 | Raise :exc:`OverflowError` if the value of *obj* is out of range for a |
| 167 | :c:type:`long`. |
| 168 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 169 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 170 | |
Mark Dickinson | f0acfee | 2012-06-23 11:14:22 +0100 | [diff] [blame] | 171 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 172 | .. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow) |
Mark Dickinson | f0acfee | 2012-06-23 11:14:22 +0100 | [diff] [blame] | 173 | |
| 174 | Return a C :c:type:`long long` representation of *obj*. If *obj* is not an |
| 175 | instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method |
| 176 | (if present) to convert it to a :c:type:`PyLongObject`. |
| 177 | |
| 178 | If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than |
| 179 | :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, |
| 180 | and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other |
| 181 | exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual. |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 182 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 183 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 184 | |
Mark Dickinson | 93f562c | 2010-01-30 10:30:15 +0000 | [diff] [blame] | 185 | .. versionadded:: 3.2 |
| 186 | |
| 187 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 188 | .. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 189 | |
| 190 | .. index:: |
| 191 | single: PY_SSIZE_T_MAX |
| 192 | single: OverflowError (built-in exception) |
| 193 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 194 | Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must |
| 195 | be an instance of :c:type:`PyLongObject`. |
| 196 | |
| 197 | Raise :exc:`OverflowError` if the value of *pylong* is out of range for a |
| 198 | :c:type:`Py_ssize_t`. |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 199 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 200 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 201 | |
Christian Heimes | 81ee3ef | 2008-05-04 22:42:01 +0000 | [diff] [blame] | 202 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 203 | .. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 204 | |
| 205 | .. index:: |
| 206 | single: ULONG_MAX |
| 207 | single: OverflowError (built-in exception) |
| 208 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 209 | Return a C :c:type:`unsigned long` representation of *pylong*. *pylong* |
| 210 | must be an instance of :c:type:`PyLongObject`. |
| 211 | |
| 212 | Raise :exc:`OverflowError` if the value of *pylong* is out of range for a |
| 213 | :c:type:`unsigned long`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 214 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 215 | Returns ``(unsigned long)-1`` on error. |
| 216 | Use :c:func:`PyErr_Occurred` to disambiguate. |
| 217 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 218 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 219 | .. c:function:: size_t PyLong_AsSize_t(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 220 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 221 | .. index:: |
| 222 | single: SIZE_MAX |
| 223 | single: OverflowError (built-in exception) |
| 224 | |
Terry Jan Reedy | 65e69b3 | 2013-03-11 17:23:46 -0400 | [diff] [blame] | 225 | Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 226 | an instance of :c:type:`PyLongObject`. |
| 227 | |
| 228 | Raise :exc:`OverflowError` if the value of *pylong* is out of range for a |
| 229 | :c:type:`size_t`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 230 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 231 | Returns ``(size_t)-1`` on error. |
| 232 | Use :c:func:`PyErr_Occurred` to disambiguate. |
| 233 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 234 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 235 | .. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 236 | |
Mark Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 237 | .. index:: |
| 238 | single: OverflowError (built-in exception) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 239 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 240 | Return a C :c:type:`unsigned long long` representation of *pylong*. *pylong* |
| 241 | must be an instance of :c:type:`PyLongObject`. |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 242 | |
| 243 | Raise :exc:`OverflowError` if the value of *pylong* is out of range for an |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 244 | :c:type:`unsigned long long`. |
Mark Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 245 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 246 | Returns ``(unsigned long long)-1`` on error. |
| 247 | Use :c:func:`PyErr_Occurred` to disambiguate. |
| 248 | |
Mark Dickinson | 2177607 | 2009-02-10 16:13:25 +0000 | [diff] [blame] | 249 | .. versionchanged:: 3.1 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 250 | A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`. |
| 251 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 252 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 253 | .. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 254 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 255 | Return a C :c:type:`unsigned long` representation of *obj*. If *obj* |
| 256 | is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__` |
| 257 | method (if present) to convert it to a :c:type:`PyLongObject`. |
| 258 | |
| 259 | If the value of *obj* is out of range for an :c:type:`unsigned long`, |
Serhiy Storchaka | 1ecf7d2 | 2016-10-27 21:41:19 +0300 | [diff] [blame] | 260 | return the reduction of that value modulo ``ULONG_MAX + 1``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 261 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 262 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 263 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 264 | |
Benjamin Peterson | 47ff073 | 2016-09-08 09:15:54 -0700 | [diff] [blame] | 265 | .. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 266 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 267 | Return a C :c:type:`unsigned long long` representation of *obj*. If *obj* |
| 268 | is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__` |
| 269 | method (if present) to convert it to a :c:type:`PyLongObject`. |
| 270 | |
| 271 | If the value of *obj* is out of range for an :c:type:`unsigned long long`, |
Serhiy Storchaka | 1ecf7d2 | 2016-10-27 21:41:19 +0300 | [diff] [blame] | 272 | return the reduction of that value modulo ``PY_ULLONG_MAX + 1``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 273 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 274 | Returns -1 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 275 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 276 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 277 | .. c:function:: double PyLong_AsDouble(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 278 | |
Mark Dickinson | b8dc3ab | 2012-06-23 12:12:52 +0100 | [diff] [blame] | 279 | Return a C :c:type:`double` representation of *pylong*. *pylong* must be |
| 280 | an instance of :c:type:`PyLongObject`. |
| 281 | |
| 282 | Raise :exc:`OverflowError` if the value of *pylong* is out of range for a |
| 283 | :c:type:`double`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 284 | |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 285 | Returns -1.0 on error. Use :c:func:`PyErr_Occurred` to disambiguate. |
| 286 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 287 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 288 | .. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 289 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 290 | Convert a Python integer *pylong* to a C :c:type:`void` pointer. |
Christian Heimes | c3f30c4 | 2008-02-22 16:37:40 +0000 | [diff] [blame] | 291 | If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 292 | is only assured to produce a usable :c:type:`void` pointer for values created |
| 293 | with :c:func:`PyLong_FromVoidPtr`. |
Gregory P. Smith | f5b04a3 | 2018-01-28 17:48:31 -0800 | [diff] [blame] | 294 | |
| 295 | Returns NULL on error. Use :c:func:`PyErr_Occurred` to disambiguate. |