整数型对象

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

在出错时,大多数 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)

如果参数是 PyLongObjectPyLongObject 的子类型,则返回 True。该函数一定能够执行成功。

int PyLong_CheckExact(PyObject *p)

如果其参数属于 PyLongObject,但不是 PyLongObject 的子类型则返回真值。 此函数总是会成功执行。

PyObject *PyLong_FromLong(long v)
返回值:新的引用。 属于 稳定 ABI.

v 返回一个新的 PyLongObject 对象,失败时返回 NULL

当前的实现维护着一个整数对象数组,包含 -5256 之间的所有整数对象。 若创建一个位于该区间的 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_FromInt32(int32_t value)
PyObject *PyLong_FromInt64(int64_t value)
属于 稳定 ABI 自 3.14 版起.

Return a new PyLongObject object from a signed C int32_t or int64_t, or NULL with an exception set on failure.

Added in version 3.14.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)
返回值:新的引用。 属于 稳定 ABI.

基于 C unsigned long long 返回一个新的 PyLongObject 对象,失败时返回 NULL

PyObject *PyLong_FromUInt32(uint32_t value)
PyObject *PyLong_FromUInt64(uint64_t value)
属于 稳定 ABI 自 3.14 版起.

Return a new PyLongObject object from an unsigned C uint32_t or uint64_t, or NULL with an exception set on failure.

Added in version 3.14.

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 中末尾而在出错时将指向第一个无法处理的字符。 如果 base0,则 str 将使用 整数字面值 定义来解读;在此情况下,非零十进制数以零开头将会引发 ValueError。 如果 base 不为 0,则必须在 236,包括这两个值。 开头和末尾的空格以及基数标示符之后和数码之间的单下划线将被忽略。 如果没有数码或 str 中数码和末尾空格之后不以 NULL 结束,则将引发 ValueError

参见

PyLong_AsNativeBytes() and PyLong_FromNativeBytes() functions can be used to convert a PyLongObject to/from an array of bytes in base 256.

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)
返回值:新的引用。

将字符串 u 中的 Unicode 数字序列转换为 Python 整数值。

Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)
返回值:新的引用。 属于 稳定 ABI.

从指针 p 创建一个 Python 整数。可以使用 PyLong_AsVoidPtr() 返回的指针值。

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

将包含在 buffer 开头 n_bytes 中的值解读为一个二的补码有符号数,基于它创建一个 Python 整数。

flags 与针对 PyLong_AsNativeBytes() 的相同。 传入 -1 将选择 CPython 编译时所用的原生端序并将假定主比特位是符号位。 传入 Py_ASNATIVEBYTES_UNSIGNED_BUFFER 将产生与调用 PyLong_FromUnsignedNativeBytes() 相同的结果。 其他旗标将被忽略。

Added in version 3.13.

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

将包含在 buffer 开头 n_bytes 中的值解读为一个无符号数,基于它创建一个Python 整数。

flags 与针对 PyLong_AsNativeBytes() 的相同。 传入 -1 将选择 CPython 编译时所用的原生端序并将假定主比特位不是符号位。 其他旗标将被忽略。

Added in version 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__()

long PyLong_AS_LONG(PyObject *obj)

一个已经 soft deprecated 的别名。 完全等价于推荐使用的 PyLong_AsLong。 特别地,它可能因 OverflowError 或其他异常而失败。

自 3.14 版本弃用: 此函数已被软弃用。

int PyLong_AsInt(PyObject *obj)
属于 稳定 ABI 自 3.13 版起.

类似于 PyLong_AsLong(),将会将结果存放到一个 C int 而不是 C long

Added in version 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() 找出具体问题。

Added in version 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__()

int PyLong_AsInt32(PyObject *obj, int32_t *value)
int PyLong_AsInt64(PyObject *obj, int64_t *value)
属于 稳定 ABI 自 3.14 版起.

Set *value to a signed C int32_t or int64_t representation of obj.

If the obj value is out of range, raise an OverflowError.

Set *value and return 0 on success. Set an exception and return -1 on error.

value must not be NULL.

Added in version 3.14.

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)
int PyLong_AsUInt64(PyObject *obj, uint64_t *value)
属于 稳定 ABI 自 3.14 版起.

Set *value to an unsigned C uint32_t or uint64_t representation of obj.

If obj is not an instance of PyLongObject, first call its __index__() method (if present) to convert it to a PyLongObject.

Set *value and return 0 on success. Set an exception and return -1 on error.

value must not be NULL.

Added in version 3.14.

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 flags)

将 Python 整数值 pylong 拷贝到一个大小为 n_bytes 的原生 buffer 中。 flags 可设为 -1 以使其行为类似于 C 强制转换类型,或是用下文中的值来控制其行为。

当发生错误时将返回 -1 并设置一个异常。 如果 pylong 无法被解读为一个整数,或者如果 pylong 为负值并且设置了 Py_ASNATIVEBYTES_REJECT_NEGATIVE 旗标就可能出现这种情况。

在其他情况下,将返回存储该值所需要的字节数量。 如果该数量小于等于 n_bytes,则将拷贝整个值。 缓冲区的 n_bytes 将全部被写入:更大的缓冲区将以零值填充。

如果返回值大于 n_bytes,该值将被截断:从该值的低位开始写入尽可能多的数位,而高位部分将被忽略。 这与典型的 C 风格向下强制转换行为相匹配。

备注

溢出不会被视为错误。 如果返回值大于 n_bytes,高位部分将被丢弃。

绝对不会返回 0

值将总是作为二的补码被拷贝。

用法示例:

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // 失败。 设置一个提示失败原因的 Python 异常。
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // 成功!
}
else {
    // 发生溢出,但 'value' 包含了截断后的
    // pylong 的低比特位部分。
}

将零值传给 n_bytes 将返回一个足够容纳该值的缓冲区大小。 这可能会大于基于技术考虑所需要的值,但也不会过于离谱。 如果 n_bytes=0,则 buffer 可能为 NULL

备注

n_bytes=0 传给此函数不是确定值所需比特位长度的准确方式。

要获取一个大小未知的完整 Python 值,可以调用此函数两次:首先确定缓冲区大小,然后填充它:

// 询问我们需要多少空间。
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // 失败。Python 已设置异常,并提供了原因
    return NULL;
}
assert(expected != 0);  // 根据 API 定义,不可能为 0
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// 安全地获取整个值
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // 已设置异常
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // 这种情况不应该发生
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// 上述预检查成功的预期情况
// ... 使用 bignum ...
free(bignum);

flags 可以是 -1 (Py_ASNATIVEBYTES_DEFAULTS) 表示选择最接近 C 强制转换类型的默认行为,或是下表中其他旗标的组合。 请注意 -1 不能与其他旗标组合使用。

目前,-1 对应于 Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER

标志位

Py_ASNATIVEBYTES_DEFAULTS

-1

Py_ASNATIVEBYTES_BIG_ENDIAN

0

Py_ASNATIVEBYTES_LITTLE_ENDIAN

1

Py_ASNATIVEBYTES_NATIVE_ENDIAN

3

Py_ASNATIVEBYTES_UNSIGNED_BUFFER

4

Py_ASNATIVEBYTES_REJECT_NEGATIVE

8

Py_ASNATIVEBYTES_ALLOW_INDEX

16

指定 Py_ASNATIVEBYTES_NATIVE_ENDIAN 将覆盖任何其他端序旗标。 传入 2 被保留用于后续版本。

在默认情况下,将会请求足够的缓冲区以包括符号位。 例如在设置 n_bytes=1 转换 128 时,该函数将返回 2 (或更大的值) 以存储一个零值符号位。

如果指定了 Py_ASNATIVEBYTES_UNSIGNED_BUFFER,将在计算大小时忽略零值符号位。 例如,这将允许将 128 放入一个单字节缓冲区。 如果目标缓冲区随后又被当作是带符号位的,则一个正数输入值可能会变成负值。 请注意此旗标不会影响对负值的处理:对于这种情况,总是会请求用作符号位的空间。

指定 Py_ASNATIVEBYTES_REJECT_NEGATIVE 将导致当 pylong 为负值时设置一个异常。 如果没有此旗标,只要至少有足够容纳一个符号位的空间就将拷贝负值,无论是否指定了 Py_ASNATIVEBYTES_UNSIGNED_BUFFER

如果指定了 Py_ASNATIVEBYTES_ALLOW_INDEX 并且传入一个非整数值,则会先调用其 __index__() 方法。 这可能导致 Python 代码执行并允许运行其他线程,在此情况下将会改变其他正在使用的对象或值。 当 flags-1 时,则不设置此选项,而非整数值将会引发 TypeError

备注

如果使用默认 flags (-1 或不带 REJECT_NEGATIVEUNSIGNED_BUFFER),则多个 Python 整数可映射为单个值而不会溢出。 例如,255-1 都可放入一个单字节缓冲区并设置其全部比特位。 这与典型的 C 强制转换行为相匹配。

Added in version 3.13.

int PyLong_GetSign(PyObject *obj, int *sign)

Get the sign of the integer object obj.

On success, set *sign to the integer sign (0, -1 or +1 for zero, negative or positive integer, respectively) and return 0.

On failure, return -1 with an exception set. This function always succeeds if obj is a PyLongObject or its subtype.

Added in version 3.14.

int PyLong_IsPositive(PyObject *obj)

Check if the integer object obj is positive (obj > 0).

If obj is an instance of PyLongObject or its subtype, return 1 when it's positive and 0 otherwise. Else set an exception and return -1.

Added in version 3.14.

int PyLong_IsNegative(PyObject *obj)

Check if the integer object obj is negative (obj < 0).

If obj is an instance of PyLongObject or its subtype, return 1 when it's negative and 0 otherwise. Else set an exception and return -1.

Added in version 3.14.

int PyLong_IsZero(PyObject *obj)

Check if the integer object obj is zero.

If obj is an instance of PyLongObject or its subtype, return 1 when it's zero and 0 otherwise. Else set an exception and return -1.

Added in version 3.14.

PyObject *PyLong_GetInfo(void)
属于 稳定 ABI.

成功时,返回一个只读的 named tuple,它保存着有关 Python 内部整数表示形式的信息。 请参阅 sys.int_info 了解关于单独字段的描述。

当失败时,将返回 NULL 并设置一个异常。

Added in version 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)
这是 不稳定 API。它可在次发布版中不经警告地改变。

如果 op 为紧凑形式则返回 1,否则返回 0。

此函数使得注重性能的代码可以实现小整数的“快速路径”。 对于紧凑值将使用 PyUnstable_Long_CompactValue();对于其他值则回退为 PyLong_As* 函数或者 PyLong_AsNativeBytes()

此项加速对于大多数用户来说是可以忽略的。

具体有哪些值会被视为紧凑形式属于实现细节并可能发生改变。

Added in version 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)
这是 不稳定 API。它可在次发布版中不经警告地改变。

如果 op 为紧凑形式,如 PyUnstable_Long_IsCompact() 所确定的,则返回它的值。

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

Added in version 3.12.

Export API

Added in version 3.14.

struct PyLongLayout

Layout of an array of "digits" ("limbs" in the GMP terminology), used to represent absolute value for arbitrary precision integers.

Use PyLong_GetNativeLayout() to get the native layout of Python int objects, used internally for integers with "big enough" absolute value.

See also sys.int_info which exposes similar information in Python.

uint8_t bits_per_digit

Bits per digit. For example, a 15 bit digit means that bits 0-14 contain meaningful information.

uint8_t digit_size

Digit size in bytes. For example, a 15 bit digit will require at least 2 bytes.

int8_t digits_order

Digits order:

  • 1 for most significant digit first

  • -1 for least significant digit first

int8_t digit_endianness

Digit endianness:

  • 1 for most significant byte first (big endian)

  • -1 for least significant byte first (little endian)

const PyLongLayout *PyLong_GetNativeLayout(void)

Get the native layout of Python int objects.

See the PyLongLayout structure.

The function must not be called before Python initialization nor after Python finalization. The returned layout is valid until Python is finalized. The layout is the same for all Python sub-interpreters in a process, and so it can be cached.

struct PyLongExport

Export of a Python int object.

There are two cases:

int64_t value

The native integer value of the exported int object. Only valid if digits is NULL.

uint8_t negative

1 if the number is negative, 0 otherwise. Only valid if digits is not NULL.

Py_ssize_t ndigits

Number of digits in digits array. Only valid if digits is not NULL.

const void *digits

Read-only array of unsigned digits. Can be NULL.

int PyLong_Export(PyObject *obj, PyLongExport *export_long)

Export a Python int object.

export_long must point to a PyLongExport structure allocated by the caller. It must not be NULL.

On success, fill in *export_long and return 0. On error, set an exception and return -1.

PyLong_FreeExport() must be called when the export is no longer needed.

CPython 实现细节: This function always succeeds if obj is a Python int object or a subclass.

void PyLong_FreeExport(PyLongExport *export_long)

Release the export export_long created by PyLong_Export().

CPython 实现细节: Calling PyLong_FreeExport() is optional if export_long->digits is NULL.

PyLongWriter API

The PyLongWriter API can be used to import an integer.

Added in version 3.14.

struct PyLongWriter

A Python int writer instance.

The instance must be destroyed by PyLongWriter_Finish() or PyLongWriter_Discard().

PyLongWriter *PyLongWriter_Create(int negative, Py_ssize_t ndigits, void **digits)

Create a PyLongWriter.

On success, allocate *digits and return a writer. On error, set an exception and return NULL.

negative is 1 if the number is negative, or 0 otherwise.

ndigits is the number of digits in the digits array. It must be greater than 0.

digits must not be NULL.

After a successful call to this function, the caller should fill in the array of digits digits and then call PyLongWriter_Finish() to get a Python int. The layout of digits is described by PyLong_GetNativeLayout().

Digits must be in the range [0; (1 << bits_per_digit) - 1] (where the bits_per_digit is the number of bits per digit). Any unused most significant digits must be set to 0.

Alternately, call PyLongWriter_Discard() to destroy the writer instance without creating an int object.

PyObject *PyLongWriter_Finish(PyLongWriter *writer)
返回值:新的引用。

Finish a PyLongWriter created by PyLongWriter_Create().

On success, return a Python int object. On error, set an exception and return NULL.

The function takes care of normalizing the digits and converts the object to a compact integer if needed.

The writer instance and the digits array are invalid after the call.

void PyLongWriter_Discard(PyLongWriter *writer)

Discard a PyLongWriter created by PyLongWriter_Create().

writer must not be NULL.

The writer instance and the digits array are invalid after the call.