整数对象¶
所有整数都实现为任意大小的“长”整数对象。
发生错误时，大多数 PyLong_As* API 返回 (return type)-1，无法与数字区分。使用 PyErr_Occurred() 进行区分。
-
PyTypeObject PyLong_Type¶
- 属于 稳定 ABI。
此
PyTypeObject实例表示 Python 整数类型。它与 Python 层中的int是同一个对象。
-
int PyLong_Check(PyObject *p)¶
如果其参数是
PyLongObject或PyLongObject的子类型，则返回真。此函数始终成功。
-
int PyLong_CheckExact(PyObject *p)¶
如果其参数是
PyLongObject，但不是PyLongObject的子类型，则返回真。此函数始终成功。
-
PyObject *PyLong_FromLong(long v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 v 返回一个新的
PyLongObject对象，或在失败时返回NULL。当前实现为所有介于
-5和256之间的整数保留了一个整数对象数组。当您在该范围内创建一个 int 时，您实际上只是获得了对现有对象的引用。
-
PyObject *PyLong_FromUnsignedLong(unsigned long v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 C unsigned long 返回一个新的
PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromSsize_t(Py_ssize_t v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 C
Py_ssize_t返回一个新的PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromSize_t(size_t v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 C
size_t返回一个新的PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromLongLong(long long v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 C long long 返回一个新的
PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从 C unsigned long long 返回一个新的
PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromDouble(double v)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从v的整数部分返回一个新的
PyLongObject对象，或在失败时返回NULL。
-
PyObject *PyLong_FromString(const char *str, char **pend, int base)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
根据str中的字符串值返回一个新的
PyLongObject，该字符串值根据base中的基数进行解释，或在失败时返回NULL。如果pend不为NULL，则在成功时*pend将指向str的末尾，或在错误时指向无法处理的第一个字符。如果base为0，则str将使用整数字面量定义进行解释；在这种情况下，非零十进制数中的前导零将引发ValueError。如果base不为0，则它必须介于2和36之间（包括）。基数说明符之后和数字之间的前导和尾随空格以及单个下划线将被忽略。如果没有数字或str在数字和尾随空格之后不是以NULL结尾的，则将引发ValueError。另请参阅
Python 方法
int.to_bytes()和int.from_bytes()用于将PyLongObject转换为/从以256为基的字节数组。您可以使用PyObject_CallMethod()从C中调用这些方法。
-
PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)¶
- 返回值：新引用。
将字符串u中的 Unicode 数字序列转换为 Python 整数值。
在 3.3 版中添加。
-
PyObject *PyLong_FromVoidPtr(void *p)¶
- 返回值：新引用。 属于 稳定 ABI 的一部分。
从指针p创建一个 Python 整数。可以使用
PyLong_AsVoidPtr()从结果值中检索指针值。
-
long PyLong_AsLong(PyObject *obj)¶
- 属于 稳定 ABI。
返回obj的 C long 表示。如果obj不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果obj的值超出 long 的范围，则引发
OverflowError。如果出错，则返回
-1。使用PyErr_Occurred()进行区分。在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)¶
- 属于 稳定 ABI。
返回obj的 C long 表示。如果obj不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果obj的值大于
LONG_MAX或小于LONG_MIN，则分别将*overflow设置为1或-1，并返回-1；否则，将*overflow设置为0。如果发生任何其他异常，则将*overflow设置为0，并像往常一样返回-1。如果出错，则返回
-1。使用PyErr_Occurred()进行区分。在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
long long PyLong_AsLongLong(PyObject *obj)¶
- 属于 稳定 ABI。
返回obj的 C long long 表示。如果obj不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果obj的值超出 long long 的范围，则引发
OverflowError。如果出错，则返回
-1。使用PyErr_Occurred()进行区分。在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)¶
- 属于 稳定 ABI。
返回obj的 C long long 表示。如果obj不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果 obj 的值大于
LLONG_MAX或小于LLONG_MIN，则将 *overflow 分别设置为1或-1，并返回-1；否则，将 *overflow 设置为0。如果发生任何其他异常，则将 *overflow 设置为0，并像往常一样返回-1。如果出错，则返回
-1。使用PyErr_Occurred()进行区分。在 3.2 版本中添加。
在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)¶
- 属于 稳定 ABI。
返回 pylong 的 C
Py_ssize_t表示。pylong 必须是PyLongObject的实例。如果 pylong 的值超出
Py_ssize_t的范围，则引发OverflowError。如果出错，则返回
-1。使用PyErr_Occurred()进行区分。
-
unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶
- 属于 稳定 ABI。
返回 pylong 的 C unsigned long 表示。pylong 必须是
PyLongObject的实例。如果 pylong 的值超出 unsigned long 的范围，则引发
OverflowError。在错误时返回
(unsigned long)-1。使用PyErr_Occurred()进行区分。
-
size_t PyLong_AsSize_t(PyObject *pylong)¶
- 属于 稳定 ABI。
返回 pylong 的 C
size_t表示。pylong 必须是PyLongObject的实例。如果 pylong 的值超出
size_t的范围，则引发OverflowError。错误时返回
(size_t)-1。使用PyErr_Occurred()进行区分。
-
unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)¶
- 属于 稳定 ABI。
返回 pylong 的 C unsigned long long 表示形式。pylong 必须是
PyLongObject的实例。如果 pylong 的值超出 unsigned long long 的范围，则引发
OverflowError。错误时返回
(unsigned long long)-1。使用PyErr_Occurred()进行区分。版本 3.1 中变更: 负数 pylong 现在会引发
OverflowError，而不是TypeError。
-
unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)¶
- 属于 稳定 ABI。
返回 obj 的 C unsigned long 表示形式。如果 obj 不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果 obj 的值超出 unsigned long 的范围，则返回该值对
ULONG_MAX + 1取模后的结果。在错误时返回
(unsigned long)-1。使用PyErr_Occurred()进行区分。在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)¶
- 属于 稳定 ABI。
返回 obj 的 C unsigned long long 表示形式。如果 obj 不是
PyLongObject的实例，则首先调用其__index__()方法（如果存在）将其转换为PyLongObject。如果obj的值超出unsigned long long的范围，则返回该值对
ULLONG_MAX + 1取模后的结果。错误时返回
(unsigned long long)-1。使用PyErr_Occurred()进行区分。在 3.8 版本中变更: 如果可用，则使用
__index__()。在 3.10 版本中变更: 此函数将不再使用
__int__()。
-
double PyLong_AsDouble(PyObject *pylong)¶
- 属于 稳定 ABI。
返回pylong的C double表示。pylong必须是
PyLongObject的实例。如果pylong的值超出double的范围，则引发
OverflowError。错误时返回
-1.0。使用PyErr_Occurred()进行区分。
-
void *PyLong_AsVoidPtr(PyObject *pylong)¶
- 属于 稳定 ABI。
将Python整数pylong转换为C void指针。如果pylong无法转换，则会引发
OverflowError。这仅保证为使用PyLong_FromVoidPtr()创建的值生成可用的void指针。错误时返回
NULL。使用PyErr_Occurred()进行区分。
-
int PyUnstable_Long_IsCompact(const PyLongObject *op)¶
- 这是不稳定API。它可能会在次要版本中发生更改，恕不另行通知。
如果op是紧凑的，则返回1，否则返回0。
此函数使性能关键代码能够为小整数实现“快速路径”。对于紧凑值，使用
PyUnstable_Long_CompactValue()；对于其他值，回退到PyLong_As*函数或调用int.to_bytes()。对于大多数用户来说，速度提升预计将微不足道。
哪些值被认为是紧凑的，这是一个实现细节，可能会发生变化。
-
Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶
- 这是不稳定API。它可能会在次要版本中发生更改，恕不另行通知。
如果 op 是紧凑的，如
PyUnstable_Long_IsCompact()所确定，则返回其值。否则，返回值未定义。