Integer Objects¶

All integers are implemented as “long” integer objects of arbitrary size.

On error, mostPyLong_As* APIs return(returntype)-1 which cannot bedistinguished from a number. UsePyErr_Occurred() to disambiguate.

typePyLongObject¶

Part of theLimited API (as an opaque struct).

This subtype ofPyObject represents a Python integer object.

PyTypeObjectPyLong_Type¶

Part of theStable ABI.

This instance ofPyTypeObject represents the Python integer type.This is the same object asint in the Python layer.

intPyLong_Check(PyObject*p)¶

Return true if its argument is aPyLongObject or a subtype ofPyLongObject. This function always succeeds.

intPyLong_CheckExact(PyObject*p)¶

Return true if its argument is aPyLongObject, but not a subtype ofPyLongObject. This function always succeeds.

PyObject*PyLong_FromLong(longv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object fromv, orNULL on failure.

The current implementation keeps an array of integer objects for all integersbetween-5 and256. When you create an int in that range you actuallyjust get back a reference to the existing object.

PyObject*PyLong_FromUnsignedLong(unsignedlongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Cunsignedlong, orNULL on failure.

PyObject*PyLong_FromSsize_t(Py_ssize_tv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a CPy_ssize_t, orNULL on failure.

PyObject*PyLong_FromSize_t(size_tv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Csize_t, orNULL on failure.

PyObject*PyLong_FromLongLong(longlongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Clonglong, orNULLon failure.

PyObject*PyLong_FromUnsignedLongLong(unsignedlonglongv)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from a Cunsignedlonglong,orNULL on failure.

PyObject*PyLong_FromDouble(doublev)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject object from the integer part ofv, orNULL on failure.

PyObject*PyLong_FromString(constchar*str,char**pend,intbase)¶

Return value: New reference. Part of theStable ABI.

Return a newPyLongObject based on the string value instr, whichis interpreted according to the radix inbase, orNULL on failure. Ifpend is non-NULL,*pend will point to the end ofstr on success orto the first character that could not be processed on error. Ifbase is0,str is interpreted using theInteger literals definition; in this case, leadingzeros in a non-zero decimal number raises aValueError. Ifbase is not0, it must be between2 and36, inclusive. Leading and trailingwhitespace and single underscores after a base specifier and between digits areignored. If there are no digits orstr is not NULL-terminated following thedigits and trailing whitespace,ValueError will be raised.

See also

Python methodsint.to_bytes() andint.from_bytes()to convert aPyLongObject to/from an array of bytes in base256. You can call those from C usingPyObject_CallMethod().

PyObject*PyLong_FromUnicodeObject(PyObject*u,intbase)¶

Return value: New reference.

Convert a sequence of Unicode digits in the stringu to a Python integervalue.

Added in version 3.3.

PyObject*PyLong_FromVoidPtr(void*p)¶

Return value: New reference. Part of theStable ABI.

Create a Python integer from the pointerp. The pointer value can beretrieved from the resulting value usingPyLong_AsVoidPtr().

longPyLong_AsLong(PyObject*obj)¶

Part of theStable ABI.

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

RaiseOverflowError if the value ofobj is out of range for along.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longPyLong_AS_LONG(PyObject*obj)¶

Asoft deprecated alias.Exactly equivalent to the preferredPyLong_AsLong. In particular,it can fail withOverflowError or another exception.

Deprecated since version 3.14:The function is soft deprecated.

longPyLong_AsLongAndOverflow(PyObject*obj,int*overflow)¶

Part of theStable ABI.

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.

If the value ofobj is greater thanLONG_MAX or less thanLONG_MIN, set*overflow to1 or-1, respectively, andreturn-1; otherwise, set*overflow to0. If any other exceptionoccurs set*overflow to0 and return-1 as usual.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longlongPyLong_AsLongLong(PyObject*obj)¶

Part of theStable ABI.

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

RaiseOverflowError if the value ofobj is out of range for alonglong.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

longlongPyLong_AsLongLongAndOverflow(PyObject*obj,int*overflow)¶

Part of theStable ABI.

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() method(if present) to convert it to aPyLongObject.

If the value ofobj is greater thanLLONG_MAX or less thanLLONG_MIN, set*overflow to1 or-1, respectively,and return-1; otherwise, set*overflow to0. If any otherexception occurs set*overflow to0 and return-1 as usual.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

Added in version 3.2.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

Py_ssize_tPyLong_AsSsize_t(PyObject*pylong)¶

Part of theStable ABI.

Return a CPy_ssize_t representation ofpylong.pylong mustbe an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for aPy_ssize_t.

Returns-1 on error. UsePyErr_Occurred() to disambiguate.

unsignedlongPyLong_AsUnsignedLong(PyObject*pylong)¶

Part of theStable ABI.

Return a Cunsignedlong representation ofpylong.pylongmust be an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for aunsignedlong.

Returns(unsignedlong)-1 on error.UsePyErr_Occurred() to disambiguate.

size_tPyLong_AsSize_t(PyObject*pylong)¶

Part of theStable ABI.

Return a Csize_t representation ofpylong.pylong must bean instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for asize_t.

Returns(size_t)-1 on error.UsePyErr_Occurred() to disambiguate.

unsignedlonglongPyLong_AsUnsignedLongLong(PyObject*pylong)¶

Part of theStable ABI.

Return a Cunsignedlonglong representation ofpylong.pylongmust be an instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for anunsignedlonglong.

Returns(unsignedlonglong)-1 on error.UsePyErr_Occurred() to disambiguate.

Changed in version 3.1:A negativepylong now raisesOverflowError, notTypeError.

unsignedlongPyLong_AsUnsignedLongMask(PyObject*obj)¶

Part of theStable ABI.

Return a Cunsignedlong representation ofobj. Ifobj is notan instance ofPyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.

If the value ofobj is out of range for anunsignedlong,return the reduction of that value moduloULONG_MAX+1.

Returns(unsignedlong)-1 on error. UsePyErr_Occurred() todisambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

unsignedlonglongPyLong_AsUnsignedLongLongMask(PyObject*obj)¶

Part of theStable ABI.

Return a Cunsignedlonglong representation ofobj. Ifobjis not an instance ofPyLongObject, first call its__index__() method (if present) to convert it to aPyLongObject.

If the value ofobj is out of range for anunsignedlonglong,return the reduction of that value moduloULLONG_MAX+1.

Returns(unsignedlonglong)-1 on error. UsePyErr_Occurred()to disambiguate.

Changed in version 3.8:Use__index__() if available.

Changed in version 3.10:This function will no longer use__int__().

doublePyLong_AsDouble(PyObject*pylong)¶

Part of theStable ABI.

Return a Cdouble representation ofpylong.pylong must bean instance ofPyLongObject.

RaiseOverflowError if the value ofpylong is out of range for adouble.

Returns-1.0 on error. UsePyErr_Occurred() to disambiguate.

void*PyLong_AsVoidPtr(PyObject*pylong)¶

Part of theStable ABI.

Convert a Python integerpylong to a Cvoid pointer.Ifpylong cannot be converted, anOverflowError will be raised. Thisis only assured to produce a usablevoid pointer for values createdwithPyLong_FromVoidPtr().

ReturnsNULL on error. UsePyErr_Occurred() to disambiguate.

PyObject*PyLong_GetInfo(void)¶

Part of theStable ABI.

On success, return a read onlynamed tuple, that holdsinformation about Python’s internal representation of integers.Seesys.int_info for description of individual fields.

On failure, returnNULL with an exception set.

Added in version 3.1.

intPyUnstable_Long_IsCompact(constPyLongObject*op)¶

This isUnstable API. It may change without warning in minor releases.

Return 1 ifop is compact, 0 otherwise.

This function makes it possible for performance-critical code to implementa “fast path” for small integers. For compact values usePyUnstable_Long_CompactValue(); for others fall back to aPyLong_As* function orcallingint.to_bytes().

The speedup is expected to be negligible for most users.

Exactly what values are considered compact is an implementation detailand is subject to change.

Added in version 3.12.

Py_ssize_tPyUnstable_Long_CompactValue(constPyLongObject*op)¶

This isUnstable API. It may change without warning in minor releases.

Ifop is compact, as determined byPyUnstable_Long_IsCompact(),return its value.

Otherwise, the return value is undefined.

Added in version 3.12.