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 of
PyObjectrepresents a Python integer object.
- PyTypeObjectPyLong_Type¶
- Part of theStable ABI.
This instance of
PyTypeObjectrepresents the Python integer type.This is the same object asintin the Python layer.
- intPyLong_Check(PyObject*p)¶
Return true if its argument is a
PyLongObjector a subtype ofPyLongObject. This function always succeeds.
- intPyLong_CheckExact(PyObject*p)¶
Return true if its argument is a
PyLongObject, but not a subtype ofPyLongObject. This function always succeeds.
- PyObject*PyLong_FromLong(longv)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject fromv, orNULLon failure.The current implementation keeps an array of integer objects for all integersbetween
-5and256. 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 new
PyLongObjectobject from a Cunsignedlong, orNULLon failure.
- PyObject*PyLong_FromSsize_t(Py_ssize_tv)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject from a CPy_ssize_t, orNULLon failure.
- PyObject*PyLong_FromSize_t(size_tv)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject from a Csize_t, orNULLon failure.
- PyObject*PyLong_FromLongLong(longlongv)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject from a Clonglong, orNULLon failure.
- PyObject*PyLong_FromUnsignedLongLong(unsignedlonglongv)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject from a Cunsignedlonglong,orNULLon failure.
- PyObject*PyLong_FromDouble(doublev)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectobject from the integer part ofv, orNULLon failure.
- PyObject*PyLong_FromString(constchar*str,char**pend,intbase)¶
- Return value: New reference. Part of theStable ABI.
Return a new
PyLongObjectbased 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 between2and36, inclusive. Leading spaces and singleunderscores after a base specifier and between digits are ignored. If thereare no digits,ValueErrorwill be raised.See also
Python methods
int.to_bytes()andint.from_bytes()to convert aPyLongObjectto/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.
New 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 using
PyLong_AsVoidPtr().
- longPyLong_AsLong(PyObject*obj)¶
- Part of theStable ABI.
Return a Clong representation ofobj. Ifobj is not aninstance of
PyLongObject, first call its__index__()method(if present) to convert it to aPyLongObject.Raise
OverflowErrorif the value ofobj is out of range for along.Returns
-1on 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_AsLongAndOverflow(PyObject*obj,int*overflow)¶
- Part of theStable ABI.
Return a Clong representation ofobj. Ifobj is not aninstance of
PyLongObject, first call its__index__()method (if present) to convert it to aPyLongObject.If the value ofobj is greater than
LONG_MAXor less thanLONG_MIN, set*overflow to1or-1, respectively, andreturn-1; otherwise, set*overflow to0. If any other exceptionoccurs set*overflow to0and return-1as usual.Returns
-1on 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 of
PyLongObject, first call its__index__()method(if present) to convert it to aPyLongObject.Raise
OverflowErrorif the value ofobj is out of range for alonglong.Returns
-1on 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 of
PyLongObject, first call its__index__()method(if present) to convert it to aPyLongObject.If the value ofobj is greater than
LLONG_MAXor less thanLLONG_MIN, set*overflow to1or-1, respectively,and return-1; otherwise, set*overflow to0. If any otherexception occurs set*overflow to0and return-1as usual.Returns
-1on error. UsePyErr_Occurred()to disambiguate.New 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 C
Py_ssize_trepresentation ofpylong.pylong mustbe an instance ofPyLongObject.Raise
OverflowErrorif the value ofpylong is out of range for aPy_ssize_t.Returns
-1on error. UsePyErr_Occurred()to disambiguate.
- unsignedlongPyLong_AsUnsignedLong(PyObject*pylong)¶
- Part of theStable ABI.
Return a Cunsignedlong representation ofpylong.pylongmust be an instance of
PyLongObject.Raise
OverflowErrorif the value ofpylong is out of range for aunsignedlong.Returns
(unsignedlong)-1on error.UsePyErr_Occurred()to disambiguate.
- size_tPyLong_AsSize_t(PyObject*pylong)¶
- Part of theStable ABI.
Return a C
size_trepresentation ofpylong.pylong must bean instance ofPyLongObject.Raise
OverflowErrorif the value ofpylong is out of range for asize_t.Returns
(size_t)-1on error.UsePyErr_Occurred()to disambiguate.
- unsignedlonglongPyLong_AsUnsignedLongLong(PyObject*pylong)¶
- Part of theStable ABI.
Return a Cunsignedlonglong representation ofpylong.pylongmust be an instance of
PyLongObject.Raise
OverflowErrorif the value ofpylong is out of range for anunsignedlonglong.Returns
(unsignedlonglong)-1on error.UsePyErr_Occurred()to disambiguate.Changed in version 3.1:A negativepylong now raises
OverflowError, notTypeError.
- unsignedlongPyLong_AsUnsignedLongMask(PyObject*obj)¶
- Part of theStable ABI.
Return a Cunsignedlong representation ofobj. Ifobj is notan instance of
PyLongObject, 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 modulo
ULONG_MAX+1.Returns
(unsignedlong)-1on 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 of
PyLongObject, 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 modulo
ULLONG_MAX+1.Returns
(unsignedlonglong)-1on 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 of
PyLongObject.Raise
OverflowErrorif the value ofpylong is out of range for adouble.Returns
-1.0on 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, an
OverflowErrorwill be raised. Thisis only assured to produce a usablevoid pointer for values createdwithPyLong_FromVoidPtr().Returns
NULLon error. UsePyErr_Occurred()to disambiguate.