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.

PyLongObject

This subtype ofPyObject represents a Python integer object.

PyTypeObjectPyLong_Type

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(long v)
Return value: New reference.

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(unsigned long v)
Return value: New reference.

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

PyObject*PyLong_FromSsize_t(Py_ssize_t v)
Return value: New reference.

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

PyObject*PyLong_FromSize_t(size_t v)
Return value: New reference.

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

PyObject*PyLong_FromLongLong(long long v)
Return value: New reference.

Return a newPyLongObject object from a Clonglong, orNULLon failure.

PyObject*PyLong_FromUnsignedLongLong(unsigned long long v)
Return value: New reference.

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

PyObject*PyLong_FromDouble(double v)
Return value: New reference.

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

PyObject*PyLong_FromString(const char *str, char **pend, int base)
Return value: New reference.

Return a newPyLongObject based on the string value instr, whichis interpreted according to the radix inbase. Ifpend is non-NULL,*pend will point to the first character instr which follows therepresentation of the number. Ifbase is0,str is interpreted usingtheInteger literals definition; in this case, leading zeros in anon-zero decimal number raises aValueError. Ifbase is not0,it must be between2 and36, inclusive. Leading spaces and singleunderscores after a base specifier and between digits are ignored. If thereare no digits,ValueError will be raised.

PyObject*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-stylePy_UNICODE API; please migrate to usingPyLong_FromUnicodeObject().

PyObject*PyLong_FromUnicodeObject(PyObject *u, int base)
Return value: New reference.

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

New in version 3.3.

PyObject*PyLong_FromVoidPtr(void *p)
Return value: New reference.

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

longPyLong_AsLong(PyObject *obj)

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() or__int__() 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.

Deprecated since version 3.8:Using__int__() is deprecated.

longPyLong_AsLongAndOverflow(PyObject *obj, int *overflow)

Return a Clong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() or__int__() 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.

Deprecated since version 3.8:Using__int__() is deprecated.

long longPyLong_AsLongLong(PyObject *obj)

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() or__int__() 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.

Deprecated since version 3.8:Using__int__() is deprecated.

long longPyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)

Return a Clonglong representation ofobj. Ifobj is not aninstance ofPyLongObject, first call its__index__() or__int__() 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.

New in version 3.2.

Changed in version 3.8:Use__index__() if available.

Deprecated since version 3.8:Using__int__() is deprecated.

Py_ssize_tPyLong_AsSsize_t(PyObject *pylong)

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.

unsigned longPyLong_AsUnsignedLong(PyObject *pylong)

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)

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.

unsigned long longPyLong_AsUnsignedLongLong(PyObject *pylong)

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.

unsigned longPyLong_AsUnsignedLongMask(PyObject *obj)

Return a Cunsignedlong representation ofobj. Ifobjis not an instance ofPyLongObject, first call its__index__() or__int__() method (if present) to convertit 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.

Deprecated since version 3.8:Using__int__() is deprecated.

unsigned long longPyLong_AsUnsignedLongLongMask(PyObject *obj)

Return a Cunsignedlonglong representation ofobj. Ifobjis not an instance ofPyLongObject, first call its__index__() or__int__() method (if present) to convertit 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.

Deprecated since version 3.8:Using__int__() is deprecated.

doublePyLong_AsDouble(PyObject *pylong)

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)

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.