All integers are implemented as “long” integer objects of arbitrary size.
On error, most PyLong_As*
APIs return (return type)-1
which cannot be
distinguished from a number. Use PyErr_Occurred()
to disambiguate.
PyLongObject
PyObject
represents a Python integer object.PyLong_Type
PyTypeObject
represents the Python integer type. This is the same object as int
in the Python layer.PyLong_Check
(PyObject *p)PyLongObject
or a subtype of PyLongObject
.PyLong_CheckExact
(PyObject *p)PyLongObject
, but not a subtype of PyLongObject
.PyLong_FromLong
(long v)Return value: New reference.
Return a new PyLongObject
object from v, or NULL
on failure.
The current implementation keeps an array of integer objects for all integers
between -5
and 256
, when you create an int in that range you actually
just get back a reference to the existing object.
PyLong_FromUnsignedLong
(unsigned long v)Return value: New reference.
Return a new PyLongObject
object from a C unsigned long
, or
NULL
on failure.
PyLong_FromSsize_t
(Py_ssize_t v)Return value: New reference.
Return a new PyLongObject
object from a C Py_ssize_t
, or
NULL
on failure.
PyLong_FromSize_t
(size_t v)Return value: New reference.
Return a new PyLongObject
object from a C size_t
, or
NULL
on failure.
PyLong_FromLongLong
(long long v)Return value: New reference.
Return a new PyLongObject
object from a C long long
, or NULL
on failure.
PyLong_FromUnsignedLongLong
(unsigned long long v)Return value: New reference.
Return a new PyLongObject
object from a C unsigned long long
,
or NULL
on failure.
PyLong_FromDouble
(double v)Return value: New reference.
Return a new PyLongObject
object from the integer part of v, or
NULL
on failure.
PyLong_FromString
(const char *str, char **pend, int base)Return value: New reference.
Return a new PyLongObject
based on the string value in str, which
is interpreted according to the radix in base. If pend is non-NULL
,
*pend will point to the first character in str which follows the
representation of the number. If base is 0
, str is interpreted using
the Integer literals definition; in this case, leading zeros in a
non-zero decimal number raises a ValueError
. If base is not 0
,
it must be between 2
and 36
, inclusive. Leading spaces and single
underscores after a base specifier and between digits are ignored. If there
are no digits, ValueError
will be raised.
PyLong_FromUnicode
(Py_UNICODE *u, Py_ssize_t length, int base)Return value: New reference.
Convert a sequence of Unicode digits to a Python integer value.
Deprecated since version 3.3, will be removed in version 3.10: Part of the old-style Py_UNICODE
API; please migrate to using
PyLong_FromUnicodeObject()
.
PyLong_FromUnicodeObject
(PyObject *u, int base)Return value: New reference.
Convert a sequence of Unicode digits in the string u to a Python integer value.
New in version 3.3.
PyLong_FromVoidPtr
(void *p)Return value: New reference.
Create a Python integer from the pointer p. The pointer value can be
retrieved from the resulting value using PyLong_AsVoidPtr()
.
PyLong_AsLong
(PyObject *obj)Return a C long
representation of obj. If obj is not an
instance of PyLongObject
, first call its __index__()
or
__int__()
method (if present) to convert it to a
PyLongObject
.
Raise OverflowError
if the value of obj is out of range for a
long
.
Returns -1
on error. Use PyErr_Occurred()
to disambiguate.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsLongAndOverflow
(PyObject *obj, int *overflow)Return a C long
representation of obj. If obj is not an
instance of PyLongObject
, first call its __index__()
or
__int__()
method (if present) to convert it to a
PyLongObject
.
If the value of obj is greater than LONG_MAX
or less than
LONG_MIN
, set *overflow to 1
or -1
, respectively, and
return -1
; otherwise, set *overflow to 0
. If any other exception
occurs set *overflow to 0
and return -1
as usual.
Returns -1
on error. Use PyErr_Occurred()
to disambiguate.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsLongLong
(PyObject *obj)Return a C long long
representation of obj. If obj is not an
instance of PyLongObject
, first call its __index__()
or
__int__()
method (if present) to convert it to a
PyLongObject
.
Raise OverflowError
if the value of obj is out of range for a
long long
.
Returns -1
on error. Use PyErr_Occurred()
to disambiguate.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsLongLongAndOverflow
(PyObject *obj, int *overflow)Return a C long long
representation of obj. If obj is not an
instance of PyLongObject
, first call its __index__()
or
__int__()
method (if present) to convert it to a
PyLongObject
.
If the value of obj is greater than LLONG_MAX
or less than
LLONG_MIN
, set *overflow to 1
or -1
, respectively,
and return -1
; otherwise, set *overflow to 0
. If any other
exception occurs set *overflow to 0
and return -1
as usual.
Returns -1
on error. Use PyErr_Occurred()
to disambiguate.
New in version 3.2.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsSsize_t
(PyObject *pylong)Return a C Py_ssize_t
representation of pylong. pylong must
be an instance of PyLongObject
.
Raise OverflowError
if the value of pylong is out of range for a
Py_ssize_t
.
Returns -1
on error. Use PyErr_Occurred()
to disambiguate.
PyLong_AsUnsignedLong
(PyObject *pylong)Return a C unsigned long
representation of pylong. pylong
must be an instance of PyLongObject
.
Raise OverflowError
if the value of pylong is out of range for a
unsigned long
.
Returns (unsigned long)-1
on error.
Use PyErr_Occurred()
to disambiguate.
PyLong_AsSize_t
(PyObject *pylong)Return a C size_t
representation of pylong. pylong must be
an instance of PyLongObject
.
Raise OverflowError
if the value of pylong is out of range for a
size_t
.
Returns (size_t)-1
on error.
Use PyErr_Occurred()
to disambiguate.
PyLong_AsUnsignedLongLong
(PyObject *pylong)Return a C unsigned long long
representation of pylong. pylong
must be an instance of PyLongObject
.
Raise OverflowError
if the value of pylong is out of range for an
unsigned long long
.
Returns (unsigned long long)-1
on error.
Use PyErr_Occurred()
to disambiguate.
Changed in version 3.1: A negative pylong now raises OverflowError
, not TypeError
.
PyLong_AsUnsignedLongMask
(PyObject *obj)Return a C unsigned long
representation of obj. If obj
is not an instance of PyLongObject
, first call its
__index__()
or __int__()
method (if present) to convert
it to a PyLongObject
.
If the value of obj is out of range for an unsigned long
,
return the reduction of that value modulo ULONG_MAX + 1
.
Returns (unsigned long)-1
on error. Use PyErr_Occurred()
to
disambiguate.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsUnsignedLongLongMask
(PyObject *obj)Return a C unsigned long long
representation of obj. If obj
is not an instance of PyLongObject
, first call its
__index__()
or __int__()
method (if present) to convert
it to a PyLongObject
.
If the value of obj is out of range for an unsigned long long
,
return the reduction of that value modulo ULLONG_MAX + 1
.
Returns (unsigned long long)-1
on error. Use PyErr_Occurred()
to disambiguate.
Changed in version 3.8: Use __index__()
if available.
Deprecated since version 3.8: Using __int__()
is deprecated.
PyLong_AsDouble
(PyObject *pylong)Return a C double
representation of pylong. pylong must be
an instance of PyLongObject
.
Raise OverflowError
if the value of pylong is out of range for a
double
.
Returns -1.0
on error. Use PyErr_Occurred()
to disambiguate.
PyLong_AsVoidPtr
(PyObject *pylong)Convert a Python integer pylong to a C void
pointer.
If pylong cannot be converted, an OverflowError
will be raised. This
is only assured to produce a usable void
pointer for values created
with PyLong_FromVoidPtr()
.
Returns NULL
on error. Use PyErr_Occurred()
to disambiguate.