Integer Objects — Python 3.13.1 documentation

long PyLong_AS_LONG ( PyObject * obj ) ¶

A soft deprecated alias. Exactly equivalent to the preferred PyLong_AsLong . In particular, it can fail with OverflowError or another exception.

Deprecated since version 3.14: The function is soft deprecated.

int PyLong_AsInt ( PyObject * obj ) ¶

属于稳定 ABI (应用程序二进制接口) since version 3.13.

类似于 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 (应用程序二进制接口) .

返回 C long 表示为 obj 。若 obj 不是实例化的 PyLongObject ，首先调用其 __index__() 方法 (若存在) 以将它转换为 PyLongObject .

若值 obj 大于 LONG_MAX 或小于 LONG_MIN , set *overflow to 1 or -1 , respectively, and return -1 ; otherwise, set *overflow to 0 . If any other exception occurs set *overflow to 0 并返回 -1 as usual.

返回 -1 当出错时。使用 PyErr_Occurred() 以消除歧义。

3.8 版改变：使用 __index__() if available.

3.10 版改变： This function will no longer use __int__() .

long long PyLong_AsLongLong ( PyObject * obj ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C long long 表示为 obj 。若 obj 不是实例化的 PyLongObject ，首先调用其 __index__() 方法 (若存在) 以将它转换为 PyLongObject .

引发 OverflowError 若值 obj 超出范围对于 long long .

返回 -1 当出错时。使用 PyErr_Occurred() 以消除歧义。

3.8 版改变：使用 __index__() if available.

3.10 版改变： This function will no longer use __int__() .

long long PyLong_AsLongLongAndOverflow ( PyObject * obj , int * overflow ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C long long 表示为 obj 。若 obj 不是实例化的 PyLongObject ，首先调用其 __index__() 方法 (若存在) 以将它转换为 PyLongObject .

若值 obj 大于 LLONG_MAX 或小于 LLONG_MIN , set *overflow to 1 or -1 , respectively, and return -1 ; otherwise, set *overflow to 0 . If any other exception occurs set *overflow to 0 并返回 -1 as usual.

返回 -1 当出错时。使用 PyErr_Occurred() 以消除歧义。

Added in version 3.2.

3.8 版改变：使用 __index__() if available.

3.10 版改变： This function will no longer use __int__() .

Py_ssize_t PyLong_AsSsize_t ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C Py_ssize_t 表示为 pylong . pylong 必须是实例化的 PyLongObject .

引发 OverflowError 若值 pylong 超出范围对于 Py_ssize_t .

返回 -1 当出错时。使用 PyErr_Occurred() 以消除歧义。

unsigned long PyLong_AsUnsignedLong ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C unsigned long 表示为 pylong . pylong 必须是实例化的 PyLongObject .

引发 OverflowError 若值 pylong 超出范围对于 unsigned long .

返回 (unsigned long)-1 当出错时。使用 PyErr_Occurred() 以消除歧义。

size_t PyLong_AsSize_t ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C size_t 表示为 pylong . pylong 必须是实例化的 PyLongObject .

引发 OverflowError 若值 pylong 超出范围对于 size_t .

返回 (size_t)-1 当出错时。使用 PyErr_Occurred() 以消除歧义。

unsigned long long PyLong_AsUnsignedLongLong ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C unsigned long long 表示为 pylong . pylong 必须是实例化的 PyLongObject .

引发 OverflowError 若值 pylong 超出范围对于 unsigned long long .

返回 (unsigned long long)-1 当出错时。使用 PyErr_Occurred() 以消除歧义。

3.1 版改变： A negative pylong 现在引发 OverflowError , not TypeError .

unsigned long PyLong_AsUnsignedLongMask ( PyObject * obj ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C unsigned long 表示为 obj 。若 obj 不是实例化的 PyLongObject ，首先调用其 __index__() 方法 (若存在) 以将它转换为 PyLongObject .

若值 obj 超出范围对于 unsigned long , return the reduction of that value modulo ULONG_MAX + 1 .

返回 (unsigned long)-1 当出错时。使用 PyErr_Occurred() 以消除歧义。

3.8 版改变：使用 __index__() if available.

3.10 版改变： This function will no longer use __int__() .

unsigned long long PyLong_AsUnsignedLongLongMask ( PyObject * obj ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C unsigned long long 表示为 obj 。若 obj 不是实例化的 PyLongObject ，首先调用其 __index__() 方法 (若存在) 以将它转换为 PyLongObject .

若值 obj 超出范围对于 unsigned long long , return the reduction of that value modulo ULLONG_MAX + 1 .

返回 (unsigned long long)-1 当出错时。使用 PyErr_Occurred() 以消除歧义。

3.8 版改变：使用 __index__() if available.

3.10 版改变： This function will no longer use __int__() .

double PyLong_AsDouble ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

返回 C double 表示为 pylong . pylong 必须是实例化的 PyLongObject .

引发 OverflowError 若值 pylong 超出范围对于 double .

返回 -1.0 当出错时。使用 PyErr_Occurred() 以消除歧义。

void * PyLong_AsVoidPtr ( PyObject * pylong ) ¶

属于稳定 ABI (应用程序二进制接口) .

转换 Python 整数 pylong 到 C void 指针。若 pylong 无法转换， OverflowError will be raised. This is only assured to produce a usable void pointer for values created with PyLong_FromVoidPtr() .

返回 NULL 当出错时。使用 PyErr_Occurred() 以消除歧义。

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

Copy the Python integer value pylong to a native buffer 的大小 n_bytes 。 flags can be set to -1 to behave similarly to a C cast, or to values documented below to control the behavior.

返回 -1 with an exception raised on error. This may happen if pylong cannot be interpreted as an integer, or if pylong was negative and the Py_ASNATIVEBYTES_REJECT_NEGATIVE flag was set.

Otherwise, returns the number of bytes required to store the value. If this is equal to or less than n_bytes , the entire value was copied. All n_bytes of the buffer are written: large buffers are padded with zeroes.

If the returned value is greater than than n_bytes , the value was truncated: as many of the lowest bits of the value as could fit are written, and the higher bits are ignored. This matches the typical behavior of a C-style downcast.

注意

Overflow is not considered an error. If the returned value is larger than n_bytes , most significant bits were discarded.

0 will never be returned.

Values are always copied as two’s-complement.

用法范例：

int32_t value;
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
if (bytes < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
else if (bytes <= (Py_ssize_t)sizeof(value)) {
    // Success!
}
else {
    // Overflow occurred, but 'value' contains the truncated
    // lowest bits of pylong.
}

Passing zero to n_bytes will return the size of a buffer that would be large enough to hold the value. This may be larger than technically necessary, but not unreasonably so. If n_bytes=0 , buffer 可以是 NULL .

注意

传递 n_bytes=0 to this function is not an accurate way to determine the bit length of the value.

To get at the entire Python value of an unknown size, the function can be called twice: first to determine the buffer size, then to fill it:

// Ask how much space we need.
Py_ssize_t expected = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
if (expected < 0) {
    // Failed. A Python exception was set with the reason.
    return NULL;
}
assert(expected != 0);  // Impossible per the API definition.
uint8_t *bignum = malloc(expected);
if (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc failed.");
    return NULL;
}
// Safely get the entire value.
Py_ssize_t bytes = PyLong_AsNativeBytes(pylong, bignum, expected, -1);
if (bytes < 0) {  // Exception has been set.
    free(bignum);
    return NULL;
}
else if (bytes > expected) {  // This should not be possible.
    PyErr_SetString(PyExc_RuntimeError,
        "Unexpected bignum truncation after a size check.");
    free(bignum);
    return NULL;
}
// The expected success given the above pre-check.
// ... use bignum ...
free(bignum);

flags 是 -1 ( Py_ASNATIVEBYTES_DEFAULTS ) to select defaults that behave most like a C cast, or a combination of the other flags in the table below. Note that -1 cannot be combined with other flags.

目前， -1 corresponds to 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`

Specifying Py_ASNATIVEBYTES_NATIVE_ENDIAN will override any other endian flags. Passing 2 is reserved.

By default, sufficient buffer will be requested to include a sign bit. For example, when converting 128 with n_bytes=1 , the function will return 2 (or more) in order to store a zero sign bit.

若 Py_ASNATIVEBYTES_UNSIGNED_BUFFER is specified, a zero sign bit will be omitted from size calculations. This allows, for example, 128 to fit in a single-byte buffer. If the destination buffer is later treated as signed, a positive input value may become negative. Note that the flag does not affect handling of negative values: for those, space for a sign bit is always requested.

Specifying Py_ASNATIVEBYTES_REJECT_NEGATIVE causes an exception to be set if pylong is negative. Without this flag, negative values will be copied provided there is enough space for at least one sign bit, regardless of whether Py_ASNATIVEBYTES_UNSIGNED_BUFFER was specified.

若 Py_ASNATIVEBYTES_ALLOW_INDEX is specified and a non-integer value is passed, its __index__() method will be called first. This may result in Python code executing and other threads being allowed to run, which could cause changes to other objects or values in use. When flags is -1 , this option is not set, and non-integer values will raise TypeError .

注意

With the default flags ( -1 ，或 UNSIGNED_BUFFER without REJECT_NEGATIVE ), multiple Python integers can map to a single value without overflow. For example, both 255 and -1 fit a single-byte buffer and set all its bits. This matches typical C cast behavior.

3.13 版添加。

PyObject * PyLong_GetInfo ( void ) ¶

属于稳定 ABI (应用程序二进制接口) .

On success, return a read only 命名元组 , that holds information about Python’s internal representation of integers. See sys.int_info for description of individual fields.

On failure, return NULL with an exception set.

Added in version 3.1.

int PyUnstable_Long_IsCompact ( const PyLongObject * op ) ¶

这为 Unstable API . It may change without warning in minor releases.

Return 1 if op is compact, 0 otherwise.

This function makes it possible for performance-critical code to implement a “fast path” for small integers. For compact values use PyUnstable_Long_CompactValue() ; for others fall back to a PyLong_As* function or PyLong_AsNativeBytes() .

The speedup is expected to be negligible for most users.

Exactly what values are considered compact is an implementation detail and is subject to change.

3.12 版添加。

Py_ssize_t PyUnstable_Long_CompactValue ( const PyLongObject * op ) ¶

这为 Unstable API . It may change without warning in minor releases.

若 op is compact, as determined by PyUnstable_Long_IsCompact() , return its value.

Otherwise, the return value is undefined.

3.12 版添加。

整数对象 ¶

上一话题

下一话题

本页