整数型对象¶

所有整数都实现为长度任意的长整数对象。

在出错时，大多数 PyLong_As* API 都会返回 (return type)-1，这与数字无法区分开。请采用 PyErr_Occurred() 来加以区分。

type PyLongObject¶: 属于受限 API (作为不透明的结构体).
表示 Python 整数对象的 PyObject 子类型。

PyTypeObject PyLong_Type¶: 属于稳定 ABI.
这个 PyTypeObject 的实例表示 Python 的整数类型。与 Python 语言中的 int 相同。

int PyLong_Check(PyObject *p)¶: 如果参数是 PyLongObject 或 PyLongObject 的子类型，则返回 True。该函数一定能够执行成功。

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() 返回的指针值。

PyObject *PyLong_FromNativeBytes(const void *buffer, size_t n_bytes, int endianness)¶

Create a Python integer from the value contained in the first n_bytes of buffer, interpreted as a two's-complement signed number.

endianness may be passed -1 for the native endian that CPython was compiled with, or else 0 for big endian and 1 for little.

在 3.13 版本加入.

PyObject *PyLong_FromUnsignedNativeBytes(const void *buffer, size_t n_bytes, int endianness)¶

Create a Python integer from the value contained in the first n_bytes of buffer, interpreted as an unsigned number.

endianness may be passed -1 for the native endian that CPython was compiled with, or else 0 for big endian and 1 for little.

在 3.13 版本加入.

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__()。

int PyLong_AsInt(PyObject *obj)¶: 属于稳定 ABI 自 3.13 版开始.
Similar to PyLong_AsLong(), but store the result in a C int instead of a C long.

在 3.13 版本加入.

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() 辨别具体问题。

Py_ssize_t PyLong_AsNativeBytes(PyObject *pylong, void *buffer, Py_ssize_t n_bytes, int endianness)¶

Copy the Python integer value to a native buffer of size n_bytes:

int value;
Py_ssize_t bytes = PyLong_AsNativeBytes(v, &value, sizeof(value), -1);
if (bytes < 0) {
    // Error occurred
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // Success!
}
else {
    // Overflow occurred, but 'value' contains truncated value
}

endianness may be passed -1 for the native endian that CPython was compiled with, or 0 for big endian and 1 for little.

Return -1 with an exception raised if pylong cannot be interpreted as an integer. Otherwise, return the size of the buffer required to store the value. If this is equal to or less than n_bytes, the entire value was copied.

Unless an exception is raised, all n_bytes of the buffer will be written with as much of the value as can fit. This allows the caller to ignore all non-negative results if the intent is to match the typical behavior of a C-style downcast. No exception is set for this case.

Values are always copied as two's-complement, and sufficient buffer will be requested to include a sign bit. For example, this may cause an value that fits into 8 bytes when treated as unsigned to request 9 bytes, even though all eight bytes were copied into the buffer. What has been omitted is the zero sign bit, which is redundant when the intention is to treat the value as unsigned.

Passing zero to n_bytes will return the requested buffer size.

备注

When the value does not fit in the provided buffer, the requested size returned from the function may be larger than necessary. Passing 0 to this function is not an accurate way to determine the bit length of a value.

在 3.13 版本加入.

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() 所确定的，则返回它的值。

在其他情况下，返回值是未定义的。

整数型对象¶

上一主题

下一主题

当前页面