整數物件¶

所有整數都實現為任意大小的“長”整數物件。

出錯時，大多數 PyLong_As* API 返回 (return type)-1，這無法與數字區分開。使用 PyErr_Occurred() 來消除歧義。

type PyLongObject¶: 屬於有限 API的一部分（作為不透明結構）。
此 PyObject 的子型別表示一個 Python 整數物件。

PyTypeObject PyLong_Type¶: 屬於穩定 ABI的一部分。
此 PyTypeObject 的例項表示 Python 整數型別。這與 Python 層中的 int 物件相同。

int PyLong_Check(PyObject *p)¶: 如果其引數是 PyLongObject 或 PyLongObject 的子型別，則返回 true。此函式始終成功。

int PyLong_CheckExact(PyObject *p)¶: 如果其引數是 PyLongObject，但不是 PyLongObject 的子型別，則返回 true。此函式始終成功。

PyObject *PyLong_FromLong(long v)¶

返回值：新引用。屬於穩定 ABI 的一部分。

從 v 返回一個新的 PyLongObject 物件，失敗時返回 NULL。

當前實現保留一個整數物件陣列，用於介於 -5 和 256 之間的所有整數。當您建立該範圍內的整數時，實際上只是獲得對現有物件的引用。

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 的一部分。
根據 base 中的基數解釋 str 中的字串值，返回一個新的 PyLongObject，失敗時返回 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 flags)¶

從 *buffer* 的前 *n_bytes* 個位元組中包含的值建立一個 Python 整數，該值被解釋為二進位制補碼有符號數。

*flags* 與 PyLong_AsNativeBytes() 相同。傳遞 -1 將選擇 CPython 編譯時使用的本機位元組序，並假定最高有效位是符號位。傳遞 Py_ASNATIVEBYTES_UNSIGNED_BUFFER 將產生與呼叫 PyLong_FromUnsignedNativeBytes() 相同的結果。其他標誌將被忽略。

在版本 3.13 中新增。

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

從 *buffer* 的前 *n_bytes* 個位元組中包含的值建立一個 Python 整數，該值被解釋為無符號數。

*flags* 與 PyLong_AsNativeBytes() 相同。傳遞 -1 將選擇 CPython 編譯時使用的本機位元組序，並假定最高有效位不是符號位。除了位元組序之外的其他標誌將被忽略。

在版本 3.13 中新增。

long PyLong_AsLong(PyObject *obj)¶

屬於穩定 ABI的一部分。

返回 *obj* 的 C long 表示。如果 *obj* 不是 PyLongObject 的例項，則首先呼叫其 __index__() 方法（如果存在）將其轉換為 PyLongObject。

如果 *obj* 的值超出 C long 的範圍，則引發 OverflowError。

錯誤時返回 -1。使用 PyErr_Occurred() 來消除歧義。

在 3.8 版本中更改: 如果可用，則使用 __index__()。

在 3.10 版本中更改: 此函式將不再使用 __int__()。

long PyLong_AS_LONG(PyObject *obj)¶: 一個軟棄用別名。完全等同於首選的 PyLong_AsLong。特別是，它可能會因 OverflowError 或其他異常而失敗。

自 3.14 版本棄用: 該函式被軟棄用。

int PyLong_AsInt(PyObject *obj)¶: 自 3.13 版本以來是穩定 ABI 的一部分。
類似於 PyLong_AsLong()，但將結果儲存在 C int 而不是 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 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) {
    // 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.
}

將零傳遞給 n_bytes 將返回足以容納該值的緩衝區大小。這可能比技術上需要的要大，但不會不合理。如果 n_bytes=0，則 buffer 可以是 NULL。

注意

將 n_bytes=0 傳遞給此函式並不是確定值位長度的準確方法。

要獲取未知大小的整個 Python 值，可以呼叫該函式兩次：首先確定緩衝區大小，然後填充它

// 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），用於選擇最像 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 放入單位元組緩衝區中。如果目標緩衝區稍後被視為有符號的，則正輸入值可能會變為負數。請注意，該標誌不影響負值的處理：對於負值，始終會請求符號位的空間。

如果 pylong 為負數，則指定 Py_ASNATIVEBYTES_REJECT_NEGATIVE 會導致設定異常。如果沒有此標誌，只要有足夠的空間容納至少一個符號位，無論是否指定了 Py_ASNATIVEBYTES_UNSIGNED_BUFFER，都會複製負值。

如果指定了 Py_ASNATIVEBYTES_ALLOW_INDEX 並且傳遞了非整數值，則將首先呼叫其 __index__() 方法。這可能會導致 Python 程式碼執行並允許其他執行緒執行，這可能會導致正在使用的其他物件或值發生更改。當 flags 為 -1 時，不會設定此選項，並且非整數值將引發 TypeError。

注意

使用預設的 flags（-1，或沒有 REJECT_NEGATIVE 的 UNSIGNED_BUFFER），多個 Python 整數可以對映到單個值而不會溢位。例如，255 和 -1 都適合單位元組緩衝區並設定其所有位。這與典型的 C 轉換行為相匹配。

在版本 3.13 中新增。

PyObject *PyLong_GetInfo(void)¶

屬於穩定 ABI的一部分。

成功時，返回一個只讀的命名元組，其中包含有關 Python 內部整數表示的資訊。有關各個欄位的說明，請參閱 sys.int_info。

失敗時，返回 NULL 並設定異常。

在版本 3.1 中新增。

int PyUnstable_Long_IsCompact(const PyLongObject *op)¶

這是不穩定 API。它可能會在次要版本中更改，恕不另行通知。

如果 op 是緊湊的，則返回 1，否則返回 0。

此函式使效能關鍵的程式碼可以為小整數實現“快速路徑”。對於緊湊值，請使用 PyUnstable_Long_CompactValue()；對於其他值，則回退到 PyLong_As* 函式或 PyLong_AsNativeBytes()。

對於大多數使用者，加速預計可以忽略不計。

哪些值被認為是緊湊的，這完全是實現細節，並且可能會發生變化。

在版本 3.12 中新增。

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶

這是不穩定 API。它可能會在次要版本中更改，恕不另行通知。

如果 op 是緊湊的，由 PyUnstable_Long_IsCompact() 確定，則返回其值。

否則，返回值是未定義的。

在版本 3.12 中新增。

整數物件¶

上一主題

下一主題

本頁