devdocs/python~3.12/c-api%2Flong.html


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92

 <span id="longobjects"></span><h1>Integer Objects</h1> <p id="index-0">All integers are implemented as “long” integer objects of arbitrary size.</p> <p>On error, most <code>PyLong_As*</code> APIs return <code>(return type)-1</code> which cannot be distinguished from a number. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <dl class="c type"> <dt class="sig sig-object c" id="c.PyLongObject">
<code>type PyLongObject</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Limited API</span></a> (as an opaque struct).</em><p>This subtype of <a class="reference internal" href="structures#c.PyObject" title="PyObject"><code>PyObject</code></a> represents a Python integer object.</p> </dd>
</dl> <dl class="c var"> <dt class="sig sig-object c" id="c.PyLong_Type">
<code>PyTypeObject PyLong_Type</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>This instance of <a class="reference internal" href="type#c.PyTypeObject" title="PyTypeObject"><code>PyTypeObject</code></a> represents the Python integer type. This is the same object as <a class="reference internal" href="../library/functions#int" title="int"><code>int</code></a> in the Python layer.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_Check">
<code>int PyLong_Check(PyObject *p)</code> </dt> <dd>
<p>Return true if its argument is a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> or a subtype of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_CheckExact">
<code>int PyLong_CheckExact(PyObject *p)</code> </dt> <dd>
<p>Return true if its argument is a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, but not a subtype of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>. This function always succeeds.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromLong">
<code>PyObject *PyLong_FromLong(long v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from <em>v</em>, or <code>NULL</code> on failure.</p> <p>The current implementation keeps an array of integer objects for all integers between <code>-5</code> and <code>256</code>. When you create an int in that range you actually just get back a reference to the existing object.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromUnsignedLong">
<code>PyObject *PyLong_FromUnsignedLong(unsigned long v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromSsize_t">
<code>PyObject *PyLong_FromSsize_t(Py_ssize_t v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from a C <a class="reference internal" href="intro#c.Py_ssize_t" title="Py_ssize_t"><code>Py_ssize_t</code></a>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromSize_t">
<code>PyObject *PyLong_FromSize_t(size_t v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from a C <code>size_t</code>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromLongLong">
<code>PyObject *PyLong_FromLongLong(long long v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from a C <span class="c-expr sig sig-inline c"><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromUnsignedLongLong">
<code>PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromDouble">
<code>PyObject *PyLong_FromDouble(double v)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> object from the integer part of <em>v</em>, or <code>NULL</code> on failure.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromString">
<code>PyObject *PyLong_FromString(const char *str, char **pend, int base)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a new <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> based on the string value in <em>str</em>, which is interpreted according to the radix in <em>base</em>, or <code>NULL</code> on failure. If <em>pend</em> is non-<code>NULL</code>, <em>*pend</em> will point to the end of <em>str</em> on success or to the first character that could not be processed on error. If <em>base</em> is <code>0</code>, <em>str</em> is interpreted using the <a class="reference internal" href="../reference/lexical_analysis#integers"><span class="std std-ref">Integer literals</span></a> definition; in this case, leading zeros in a non-zero decimal number raises a <a class="reference internal" href="../library/exceptions#ValueError" title="ValueError"><code>ValueError</code></a>. If <em>base</em> is not <code>0</code>, it must be between <code>2</code> and <code>36</code>, inclusive. Leading and trailing whitespace and single underscores after a base specifier and between digits are ignored. If there are no digits or <em>str</em> is not NULL-terminated following the digits and trailing whitespace, <a class="reference internal" href="../library/exceptions#ValueError" title="ValueError"><code>ValueError</code></a> will be raised.</p> <div class="admonition seealso"> <p class="admonition-title">See also</p> <p>Python methods <a class="reference internal" href="../library/stdtypes#int.to_bytes" title="int.to_bytes"><code>int.to_bytes()</code></a> and <a class="reference internal" href="../library/stdtypes#int.from_bytes" title="int.from_bytes"><code>int.from_bytes()</code></a> to convert a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a> to/from an array of bytes in base <code>256</code>. You can call those from C using <a class="reference internal" href="call#c.PyObject_CallMethod" title="PyObject_CallMethod"><code>PyObject_CallMethod()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromUnicodeObject">
<code>PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><p>Convert a sequence of Unicode digits in the string <em>u</em> to a Python integer value.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.3.</span></p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_FromVoidPtr">
<code>PyObject *PyLong_FromVoidPtr(void *p)</code> </dt> <dd>
<em class="refcount">Return value: New reference.</em><em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Create a Python integer from the pointer <em>p</em>. The pointer value can be retrieved from the resulting value using <a class="reference internal" href="#c.PyLong_AsVoidPtr" title="PyLong_AsVoidPtr"><code>PyLong_AsVoidPtr()</code></a>.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsLong">
<code>long PyLong_AsLong(PyObject *obj)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-1">Return a C <span class="c-expr sig sig-inline c"><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>obj</em> is out of range for a <span class="c-expr sig sig-inline c"><span class="kt">long</span></span>.</p> <p>Returns <code>-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsLongAndOverflow">
<code>long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a C <span class="c-expr sig sig-inline c"><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>If the value of <em>obj</em> is greater than <code>LONG_MAX</code> or less than <code>LONG_MIN</code>, set <em>*overflow</em> to <code>1</code> or <code>-1</code>, respectively, and return <code>-1</code>; otherwise, set <em>*overflow</em> to <code>0</code>. If any other exception occurs set <em>*overflow</em> to <code>0</code> and return <code>-1</code> as usual.</p> <p>Returns <code>-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsLongLong">
<code>long long PyLong_AsLongLong(PyObject *obj)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-2">Return a C <span class="c-expr sig sig-inline c"><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>obj</em> is out of range for a <span class="c-expr sig sig-inline c"><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span>.</p> <p>Returns <code>-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsLongLongAndOverflow">
<code>long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a C <span class="c-expr sig sig-inline c"><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>If the value of <em>obj</em> is greater than <code>LLONG_MAX</code> or less than <code>LLONG_MIN</code>, set <em>*overflow</em> to <code>1</code> or <code>-1</code>, respectively, and return <code>-1</code>; otherwise, set <em>*overflow</em> to <code>0</code>. If any other exception occurs set <em>*overflow</em> to <code>0</code> and return <code>-1</code> as usual.</p> <p>Returns <code>-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.2.</span></p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsSsize_t">
<code>Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-3">Return a C <a class="reference internal" href="intro#c.Py_ssize_t" title="Py_ssize_t"><code>Py_ssize_t</code></a> representation of <em>pylong</em>. <em>pylong</em> must be an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>pylong</em> is out of range for a <a class="reference internal" href="intro#c.Py_ssize_t" title="Py_ssize_t"><code>Py_ssize_t</code></a>.</p> <p>Returns <code>-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsUnsignedLong">
<code>unsigned long PyLong_AsUnsignedLong(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-4">Return a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>pylong</em>. <em>pylong</em> must be an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>pylong</em> is out of range for a <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span>.</p> <p>Returns <code>(unsigned long)-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsSize_t">
<code>size_t PyLong_AsSize_t(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-5">Return a C <code>size_t</code> representation of <em>pylong</em>. <em>pylong</em> must be an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>pylong</em> is out of range for a <code>size_t</code>.</p> <p>Returns <code>(size_t)-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsUnsignedLongLong">
<code>unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p id="index-6">Return a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>pylong</em>. <em>pylong</em> must be an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>pylong</em> is out of range for an <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span>.</p> <p>Returns <code>(unsigned long long)-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.1: </span>A negative <em>pylong</em> now raises <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a>, not <a class="reference internal" href="../library/exceptions#TypeError" title="TypeError"><code>TypeError</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsUnsignedLongMask">
<code>unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>If the value of <em>obj</em> is out of range for an <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span></span>, return the reduction of that value modulo <code>ULONG_MAX + 1</code>.</p> <p>Returns <code>(unsigned long)-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsUnsignedLongLongMask">
<code>unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a C <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span> representation of <em>obj</em>. If <em>obj</em> is not an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>, first call its <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> method (if present) to convert it to a <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>If the value of <em>obj</em> is out of range for an <span class="c-expr sig sig-inline c"><span class="kt">unsigned</span><span class="w"> </span><span class="kt">long</span><span class="w"> </span><span class="kt">long</span></span>, return the reduction of that value modulo <code>ULLONG_MAX + 1</code>.</p> <p>Returns <code>(unsigned long long)-1</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Use <a class="reference internal" href="../reference/datamodel#object.__index__" title="object.__index__"><code>__index__()</code></a> if available.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.10: </span>This function will no longer use <a class="reference internal" href="../reference/datamodel#object.__int__" title="object.__int__"><code>__int__()</code></a>.</p> </div> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsDouble">
<code>double PyLong_AsDouble(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Return a C <span class="c-expr sig sig-inline c"><span class="kt">double</span></span> representation of <em>pylong</em>. <em>pylong</em> must be an instance of <a class="reference internal" href="#c.PyLongObject" title="PyLongObject"><code>PyLongObject</code></a>.</p> <p>Raise <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> if the value of <em>pylong</em> is out of range for a <span class="c-expr sig sig-inline c"><span class="kt">double</span></span>.</p> <p>Returns <code>-1.0</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyLong_AsVoidPtr">
<code>void *PyLong_AsVoidPtr(PyObject *pylong)</code> </dt> <dd>
<em class="stableabi"> Part of the <a class="reference internal" href="stable#stable"><span class="std std-ref">Stable ABI</span></a>.</em><p>Convert a Python integer <em>pylong</em> to a C <span class="c-expr sig sig-inline c"><span class="kt">void</span></span> pointer. If <em>pylong</em> cannot be converted, an <a class="reference internal" href="../library/exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> will be raised. This is only assured to produce a usable <span class="c-expr sig sig-inline c"><span class="kt">void</span></span> pointer for values created with <a class="reference internal" href="#c.PyLong_FromVoidPtr" title="PyLong_FromVoidPtr"><code>PyLong_FromVoidPtr()</code></a>.</p> <p>Returns <code>NULL</code> on error. Use <a class="reference internal" href="exceptions#c.PyErr_Occurred" title="PyErr_Occurred"><code>PyErr_Occurred()</code></a> to disambiguate.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_Long_IsCompact">
<code>int PyUnstable_Long_IsCompact(const PyLongObject *op)</code> </dt> <dd>
<div class="unstable-c-api warning admonition"> <em>This is <a class="reference internal" href="stable#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em>
</div> <p>Return 1 if <em>op</em> is compact, 0 otherwise.</p> <p>This function makes it possible for performance-critical code to implement a “fast path” for small integers. For compact values use <a class="reference internal" href="#c.PyUnstable_Long_CompactValue" title="PyUnstable_Long_CompactValue"><code>PyUnstable_Long_CompactValue()</code></a>; for others fall back to a <a class="reference internal" href="#c.PyLong_AsSize_t" title="PyLong_AsSize_t"><code>PyLong_As*</code></a> function or <a class="reference internal" href="call#c.PyObject_CallMethod" title="PyObject_CallMethod"><code>calling</code></a> <a class="reference internal" href="../library/stdtypes#int.to_bytes" title="int.to_bytes"><code>int.to_bytes()</code></a>.</p> <p>The speedup is expected to be negligible for most users.</p> <p>Exactly what values are considered compact is an implementation detail and is subject to change.</p> </dd>
</dl> <dl class="c function"> <dt class="sig sig-object c" id="c.PyUnstable_Long_CompactValue">
<code>Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)</code> </dt> <dd>
<div class="unstable-c-api warning admonition"> <em>This is <a class="reference internal" href="stable#unstable-c-api"><span class="std std-ref">Unstable API</span></a>. It may change without warning in minor releases.</em>
</div> <p>If <em>op</em> is compact, as determined by <a class="reference internal" href="#c.PyUnstable_Long_IsCompact" title="PyUnstable_Long_IsCompact"><code>PyUnstable_Long_IsCompact()</code></a>, return its value.</p> <p>Otherwise, the return value is undefined.</p> </dd>
</dl> <div class="_attribution">
  <p class="_attribution-p">
    &copy; 2001&ndash;2023 Python Software Foundation<br>Licensed under the PSF License.<br>
    <a href="https://docs.python.org/3.12/c-api/long.html" class="_attribution-link">https://docs.python.org/3.12/c-api/long.html</a>
  </p>
</div>