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. 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 50.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v) 51 52 Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or 53 ``NULL`` on failure. 54 55 56.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) 57 58 Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or 59 ``NULL`` on failure. 60 61 62.. c:function:: PyObject* PyLong_FromSize_t(size_t v) 63 64 Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or 65 ``NULL`` on failure. 66 67 68.. c:function:: PyObject* PyLong_FromLongLong(long long v) 69 70 Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or ``NULL`` 71 on failure. 72 73 74.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v) 75 76 Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`, 77 or ``NULL`` on failure. 78 79 80.. c:function:: PyObject* PyLong_FromDouble(double v) 81 82 Return a new :c:type:`PyLongObject` object from the integer part of *v*, or 83 ``NULL`` on failure. 84 85 86.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base) 87 88 Return a new :c:type:`PyLongObject` based on the string value in *str*, which 89 is 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``, *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. 97 98 99.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base) 100 101 Convert a sequence of Unicode digits to a Python integer value. 102 103 .. deprecated-removed:: 3.3 3.10 104 Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using 105 :c:func:`PyLong_FromUnicodeObject`. 106 107 108.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base) 109 110 Convert a sequence of Unicode digits in the string *u* to a Python integer 111 value. 112 113 .. versionadded:: 3.3 114 115 116.. c:function:: PyObject* PyLong_FromVoidPtr(void *p) 117 118 Create a Python integer from the pointer *p*. The pointer value can be 119 retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`. 120 121 122.. XXX alias PyLong_AS_LONG (for now) 123.. c:function:: long PyLong_AsLong(PyObject *obj) 124 125 .. index:: 126 single: LONG_MAX 127 single: OverflowError (built-in exception) 128 129 Return a C :c:type:`long` representation of *obj*. If *obj* is not an 130 instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or 131 :meth:`__int__` method (if present) to convert it to a 132 :c:type:`PyLongObject`. 133 134 Raise :exc:`OverflowError` if the value of *obj* is out of range for a 135 :c:type:`long`. 136 137 Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 138 139 .. versionchanged:: 3.8 140 Use :meth:`__index__` if available. 141 142 .. deprecated:: 3.8 143 Using :meth:`__int__` is deprecated. 144 145 146.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow) 147 148 Return a C :c:type:`long` representation of *obj*. If *obj* is not an 149 instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or 150 :meth:`__int__` method (if present) to convert it to a 151 :c:type:`PyLongObject`. 152 153 If the value of *obj* is greater than :const:`LONG_MAX` or less than 154 :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and 155 return ``-1``; otherwise, set *\*overflow* to ``0``. If any other exception 156 occurs set *\*overflow* to ``0`` and return ``-1`` as usual. 157 158 Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 159 160 .. versionchanged:: 3.8 161 Use :meth:`__index__` if available. 162 163 .. deprecated:: 3.8 164 Using :meth:`__int__` is deprecated. 165 166 167.. c:function:: long long PyLong_AsLongLong(PyObject *obj) 168 169 .. index:: 170 single: OverflowError (built-in exception) 171 172 Return a C :c:type:`long long` representation of *obj*. If *obj* is not an 173 instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or 174 :meth:`__int__` method (if present) to convert it to a 175 :c:type:`PyLongObject`. 176 177 Raise :exc:`OverflowError` if the value of *obj* is out of range for a 178 :c:type:`long long`. 179 180 Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 181 182 .. versionchanged:: 3.8 183 Use :meth:`__index__` if available. 184 185 .. deprecated:: 3.8 186 Using :meth:`__int__` is deprecated. 187 188 189.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow) 190 191 Return a C :c:type:`long long` representation of *obj*. If *obj* is not an 192 instance of :c:type:`PyLongObject`, first call its :meth:`__index__` or 193 :meth:`__int__` method (if present) to convert it to a 194 :c:type:`PyLongObject`. 195 196 If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than 197 :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, 198 and return ``-1``; otherwise, set *\*overflow* to ``0``. If any other 199 exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual. 200 201 Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 202 203 .. versionadded:: 3.2 204 205 .. versionchanged:: 3.8 206 Use :meth:`__index__` if available. 207 208 .. deprecated:: 3.8 209 Using :meth:`__int__` is deprecated. 210 211 212.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) 213 214 .. index:: 215 single: PY_SSIZE_T_MAX 216 single: OverflowError (built-in exception) 217 218 Return a C :c:type:`Py_ssize_t` representation of *pylong*. *pylong* must 219 be an instance of :c:type:`PyLongObject`. 220 221 Raise :exc:`OverflowError` if the value of *pylong* is out of range for a 222 :c:type:`Py_ssize_t`. 223 224 Returns ``-1`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 225 226 227.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong) 228 229 .. index:: 230 single: ULONG_MAX 231 single: OverflowError (built-in exception) 232 233 Return a C :c:type:`unsigned long` representation of *pylong*. *pylong* 234 must be an instance of :c:type:`PyLongObject`. 235 236 Raise :exc:`OverflowError` if the value of *pylong* is out of range for a 237 :c:type:`unsigned long`. 238 239 Returns ``(unsigned long)-1`` on error. 240 Use :c:func:`PyErr_Occurred` to disambiguate. 241 242 243.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong) 244 245 .. index:: 246 single: SIZE_MAX 247 single: OverflowError (built-in exception) 248 249 Return a C :c:type:`size_t` representation of *pylong*. *pylong* must be 250 an instance of :c:type:`PyLongObject`. 251 252 Raise :exc:`OverflowError` if the value of *pylong* is out of range for a 253 :c:type:`size_t`. 254 255 Returns ``(size_t)-1`` on error. 256 Use :c:func:`PyErr_Occurred` to disambiguate. 257 258 259.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong) 260 261 .. index:: 262 single: OverflowError (built-in exception) 263 264 Return a C :c:type:`unsigned long long` representation of *pylong*. *pylong* 265 must be an instance of :c:type:`PyLongObject`. 266 267 Raise :exc:`OverflowError` if the value of *pylong* is out of range for an 268 :c:type:`unsigned long long`. 269 270 Returns ``(unsigned long long)-1`` on error. 271 Use :c:func:`PyErr_Occurred` to disambiguate. 272 273 .. versionchanged:: 3.1 274 A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`. 275 276 277.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj) 278 279 Return a C :c:type:`unsigned long` representation of *obj*. If *obj* 280 is not an instance of :c:type:`PyLongObject`, first call its 281 :meth:`__index__` or :meth:`__int__` method (if present) to convert 282 it to a :c:type:`PyLongObject`. 283 284 If the value of *obj* is out of range for an :c:type:`unsigned long`, 285 return the reduction of that value modulo ``ULONG_MAX + 1``. 286 287 Returns ``(unsigned long)-1`` on error. Use :c:func:`PyErr_Occurred` to 288 disambiguate. 289 290 .. versionchanged:: 3.8 291 Use :meth:`__index__` if available. 292 293 .. deprecated:: 3.8 294 Using :meth:`__int__` is deprecated. 295 296 297.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj) 298 299 Return a C :c:type:`unsigned long long` representation of *obj*. If *obj* 300 is not an instance of :c:type:`PyLongObject`, first call its 301 :meth:`__index__` or :meth:`__int__` method (if present) to convert 302 it to a :c:type:`PyLongObject`. 303 304 If the value of *obj* is out of range for an :c:type:`unsigned long long`, 305 return the reduction of that value modulo ``PY_ULLONG_MAX + 1``. 306 307 Returns ``(unsigned long long)-1`` on error. Use :c:func:`PyErr_Occurred` 308 to disambiguate. 309 310 .. versionchanged:: 3.8 311 Use :meth:`__index__` if available. 312 313 .. deprecated:: 3.8 314 Using :meth:`__int__` is deprecated. 315 316 317.. c:function:: double PyLong_AsDouble(PyObject *pylong) 318 319 Return a C :c:type:`double` representation of *pylong*. *pylong* must be 320 an instance of :c:type:`PyLongObject`. 321 322 Raise :exc:`OverflowError` if the value of *pylong* is out of range for a 323 :c:type:`double`. 324 325 Returns ``-1.0`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 326 327 328.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) 329 330 Convert a Python integer *pylong* to a C :c:type:`void` pointer. 331 If *pylong* cannot be converted, an :exc:`OverflowError` will be raised. This 332 is only assured to produce a usable :c:type:`void` pointer for values created 333 with :c:func:`PyLong_FromVoidPtr`. 334 335 Returns ``NULL`` on error. Use :c:func:`PyErr_Occurred` to disambiguate. 336