Đối tượng số nguyên¶

Tất cả các số nguyên được triển khai dưới dạng đối tượng số nguyên "dài" có kích thước tùy ý.

Nếu có lỗi, hầu hết các API PyLong_As* đều trả về (return type)-1 không thể phân biệt được với một số. Sử dụng PyErr_Occurred() để phân biệt.

type PyLongObject¶: Một phần của API có giới hạn (như một cấu trúc mờ đục).
Kiểu con này của PyObject đại diện cho một đối tượng số nguyên Python.

PyTypeObject PyLong_Type¶: Một phần của ABI ổn định.
Phiên bản PyTypeObject này đại diện cho kiểu số nguyên Python. Đây là đối tượng tương tự như int trong lớp Python.

int PyLong_Check(PyObject *p)¶: Trả về true nếu đối số của nó là PyLongObject hoặc kiểu con của PyLongObject. Chức năng này luôn thành công.

int PyLong_CheckExact(PyObject *p)¶: Trả về true nếu đối số của nó là PyLongObject nhưng không phải là kiểu con của PyLongObject. Chức năng này luôn thành công.

PyObject *PyLong_FromLong(long v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ v hoặc NULL khi thất bại.

CPython giữ một mảng các đối tượng số nguyên cho tất cả các số nguyên nằm trong khoảng từ -5 đến 256. Khi bạn tạo một int trong phạm vi đó, bạn thực sự chỉ lấy lại một tham chiếu đến đối tượng hiện có.

PyObject *PyLong_FromUnsignedLong(unsigned long v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ C unsigned long hoặc NULL khi bị lỗi.

PyObject *PyLong_FromSsize_t(Py_ssize_t v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ C Py_ssize_t hoặc NULL khi bị lỗi.

PyObject *PyLong_FromSize_t(size_t v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ C size_t hoặc NULL khi bị lỗi.

PyObject *PyLong_FromLongLong(long long v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ C long long hoặc NULL khi bị lỗi.

PyObject *PyLong_FromInt32(int32_t value)¶
PyObject *PyLong_FromInt64(int64_t value)¶: Một phần của ABI ổn định kể từ phiên bản 3.14.
Trả về một đối tượng PyLongObject mới từ một int32_t hoặc int64_t C đã ký hoặc NULL với một ngoại lệ được đặt là lỗi.

Added in version 3.14.

PyObject *PyLong_FromUnsignedLongLong(unsigned long long v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ C unsigned long long hoặc NULL khi bị lỗi.

PyObject *PyLong_FromUInt32(uint32_t value)¶
PyObject *PyLong_FromUInt64(uint64_t value)¶: Một phần của ABI ổn định kể từ phiên bản 3.14.
Trả về một đối tượng PyLongObject mới từ một uint32_t hoặc uint64_t C chưa được ký hoặc NULL với một ngoại lệ được đặt là lỗi.

Added in version 3.14.

PyObject *PyLong_FromDouble(double v)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một đối tượng PyLongObject mới từ phần nguyên của v hoặc NULL khi thất bại.

PyObject *PyLong_FromString(const char *str, char **pend, int base)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về một PyLongObject mới dựa trên giá trị chuỗi trong str, được diễn giải theo cơ số trong base hoặc NULL khi thất bại. Nếu pend không phải là NULL, *pend sẽ trỏ đến phần cuối của str nếu thành công hoặc tới ký tự đầu tiên không thể xử lý do lỗi. Nếu base là 0, str sẽ được diễn giải bằng định nghĩa Chữ số nguyên; trong trường hợp này, các số 0 đứng đầu trong số thập phân khác 0 sẽ tạo ra ValueError. Nếu base không phải là 0 thì nó phải nằm trong khoảng từ 2 đến 36. Khoảng trắng đầu và cuối cũng như dấu gạch dưới đơn sau bộ xác định cơ sở và giữa các chữ số đều bị bỏ qua. Nếu không có chữ số hoặc str không bị NULL chấm dứt theo các chữ số và khoảng trắng ở cuối, ValueError sẽ được nâng lên.

Xem thêm

Các hàm PyLong_AsNativeBytes() và PyLong_FromNativeBytes() có thể được sử dụng để chuyển đổi PyLongObject thành/từ một mảng byte trong cơ sở 256.

PyObject *PyLong_FromUnicodeObject(PyObject *u, int base)¶: Giá trị trả về: Tham chiếu mới.
Chuyển đổi một chuỗi các chữ số Unicode trong chuỗi u thành giá trị số nguyên Python.

Added in version 3.3.

PyObject *PyLong_FromVoidPtr(void *p)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một số nguyên Python từ con trỏ p. Giá trị con trỏ có thể được lấy từ giá trị kết quả bằng PyLong_AsVoidPtr().

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

Một phần của ABI ổn định kể từ phiên bản 3.14.

Tạo một số nguyên Python từ giá trị chứa trong n_bytes đầu tiên của buffer, được hiểu là số có dấu bù hai.

flags cũng giống như PyLong_AsNativeBytes(). Việc chuyển -1 sẽ chọn endian gốc mà CPython được biên dịch và giả sử rằng bit quan trọng nhất là bit dấu. Việc chuyển Py_ASNATIVEBYTES_UNSIGNED_BUFFER sẽ cho kết quả tương tự như gọi PyLong_FromUnsignedNativeBytes(). Các cờ khác bị bỏ qua.

Added in version 3.13.

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

Một phần của ABI ổn định kể từ phiên bản 3.14.

Tạo một số nguyên Python từ giá trị chứa trong n_bytes đầu tiên của buffer, được hiểu là số không dấu.

flags cũng giống như PyLong_AsNativeBytes(). Việc chuyển -1 sẽ chọn endian gốc mà CPython được biên dịch và giả định rằng bit quan trọng nhất không phải là bit dấu. Các cờ khác ngoài endian sẽ bị bỏ qua.

Added in version 3.13.

PyLong_FromPid(pid)¶

Macro để tạo số nguyên Python từ mã định danh quy trình.

Điều này có thể được định nghĩa là bí danh của PyLong_FromLong() hoặc PyLong_FromLongLong(), tùy thuộc vào kích thước của loại PID của hệ thống.

Added in version 3.2.

long PyLong_AsLong(PyObject *obj)¶

Một phần của ABI ổn định.

Trả về biểu diễn C long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Tăng OverflowError nếu giá trị của obj nằm ngoài phạm vi của long.

Trả về -1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

long PyLong_AS_LONG(PyObject *obj)¶: Bí danh soft deprecated. Hoàn toàn tương đương với PyLong_AsLong ưa thích. Đặc biệt, nó có thể bị lỗi với OverflowError hoặc ngoại lệ khác.

Sắp loại bỏ từ phiên bản 3.14: Chức năng này không còn được dùng nữa.

int PyLong_AsInt(PyObject *obj)¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Tương tự như PyLong_AsLong(), nhưng lưu kết quả vào C int thay vì C long.

Added in version 3.13.

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

Một phần của ABI ổn định.

Trả về biểu diễn C long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu giá trị của obj lớn hơn LONG_MAX hoặc nhỏ hơn LONG_MIN, hãy đặt *overflow thành 1 hoặc -1 tương ứng và trả về -1; nếu không, hãy đặt *overflow thành 0. Nếu có bất kỳ ngoại lệ nào khác xảy ra, hãy đặt *overflow thành 0 và trả về -1 như bình thường.

Trả về -1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

long long PyLong_AsLongLong(PyObject *obj)¶

Một phần của ABI ổn định.

Trả về biểu diễn C long long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Tăng OverflowError nếu giá trị của obj nằm ngoài phạm vi của long long.

Trả về -1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

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

Một phần của ABI ổn định.

Trả về biểu diễn C long long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu giá trị của obj lớn hơn LLONG_MAX hoặc nhỏ hơn LLONG_MIN, hãy đặt *overflow thành 1 hoặc -1 tương ứng và trả về -1; nếu không, hãy đặt *overflow thành 0. Nếu có bất kỳ ngoại lệ nào khác xảy ra, hãy đặt *overflow thành 0 và trả về -1 như bình thường.

Trả về -1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Added in version 3.2.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)¶

Một phần của ABI ổn định.

Trả về biểu diễn C Py_ssize_t của pylong. pylong phải là một phiên bản của PyLongObject.

Tăng OverflowError nếu giá trị của pylong nằm ngoài phạm vi của Py_ssize_t.

Trả về -1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

unsigned long PyLong_AsUnsignedLong(PyObject *pylong)¶

Một phần của ABI ổn định.

Trả về biểu diễn C unsigned long của pylong. pylong phải là một phiên bản của PyLongObject.

Tăng OverflowError nếu giá trị của pylong nằm ngoài phạm vi của unsigned long.

Trả về (unsigned long)-1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

size_t PyLong_AsSize_t(PyObject *pylong)¶

Một phần của ABI ổn định.

Trả về biểu diễn C size_t của pylong. pylong phải là một phiên bản của PyLongObject.

Tăng OverflowError nếu giá trị của pylong nằm ngoài phạm vi của size_t.

Trả về (size_t)-1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)¶

Một phần của ABI ổn định.

Trả về biểu diễn C unsigned long long của pylong. pylong phải là một phiên bản của PyLongObject.

Tăng OverflowError nếu giá trị của pylong nằm ngoài phạm vi của unsigned long long.

Trả về (unsigned long long)-1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.1: Một pylong âm bây giờ tăng OverflowError chứ không phải TypeError.

unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)¶

Một phần của ABI ổn định.

Trả về biểu diễn C unsigned long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu giá trị của obj nằm ngoài phạm vi của unsigned long, hãy trả về mức giảm của giá trị đó theo modulo ULONG_MAX + 1.

Trả về (unsigned long)-1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)¶

Một phần của ABI ổn định.

Trả về biểu diễn C unsigned long long của obj. Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu giá trị của obj nằm ngoài phạm vi của unsigned long long, hãy trả về mức giảm của giá trị đó theo modulo ULLONG_MAX + 1.

Trả về (unsigned long long)-1 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

Thay đổi trong phiên bản 3.8: Sử dụng __index__() nếu có.

Thay đổi trong phiên bản 3.10: Chức năng này sẽ không còn sử dụng __int__() nữa.

int PyLong_AsInt32(PyObject *obj, int32_t *value)¶

int PyLong_AsInt64(PyObject *obj, int64_t *value)¶

Một phần của ABI ổn định kể từ phiên bản 3.14.

Đặt *value thành biểu diễn C int32_t hoặc int64_t đã ký của obj.

Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu giá trị obj nằm ngoài phạm vi, hãy tăng OverflowError.

Đặt *value và trả về 0 nếu thành công. Đặt một ngoại lệ và trả về -1 khi có lỗi.

value không được là NULL.

Added in version 3.14.

int PyLong_AsUInt32(PyObject *obj, uint32_t *value)¶

int PyLong_AsUInt64(PyObject *obj, uint64_t *value)¶

Một phần của ABI ổn định kể từ phiên bản 3.14.

Đặt *value thành biểu diễn C uint32_t hoặc uint64_t không dấu của obj.

Nếu obj không phải là một phiên bản của PyLongObject, trước tiên hãy gọi phương thức __index__() của nó (nếu có) để chuyển đổi nó thành PyLongObject.

Nếu obj âm, hãy tăng ValueError.
Nếu giá trị obj nằm ngoài phạm vi, hãy tăng OverflowError.

Đặt *value và trả về 0 nếu thành công. Đặt một ngoại lệ và trả về -1 khi có lỗi.

value không được là NULL.

Added in version 3.14.

double PyLong_AsDouble(PyObject *pylong)¶

Một phần của ABI ổn định.

Trả về biểu diễn C double của pylong. pylong phải là một phiên bản của PyLongObject.

Tăng OverflowError nếu giá trị của pylong nằm ngoài phạm vi của double.

Trả về -1.0 do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

void *PyLong_AsVoidPtr(PyObject *pylong)¶

Một phần của ABI ổn định.

Chuyển đổi số nguyên pylong của Python thành con trỏ C void. Nếu không thể chuyển đổi pylong, OverflowError sẽ được nâng lên. Điều này chỉ được đảm bảo để tạo ra một con trỏ void có thể sử dụng được cho các giá trị được tạo bằng PyLong_FromVoidPtr().

Trả về NULL do lỗi. Sử dụng PyErr_Occurred() để phân biệt.

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

Một phần của ABI ổn định kể từ phiên bản 3.14.

Sao chép giá trị số nguyên pylong của Python sang buffer gốc có kích thước n_bytes. flags có thể được đặt thành -1 để hoạt động tương tự như dàn diễn viên C hoặc thành các giá trị được ghi lại bên dưới để kiểm soát hành vi.

Trả về -1 với ngoại lệ được đưa ra do lỗi. Điều này có thể xảy ra nếu pylong không thể được hiểu là số nguyên hoặc nếu pylong âm và cờ Py_ASNATIVEBYTES_REJECT_NEGATIVE được đặt.

Ngược lại, trả về số byte cần thiết để lưu trữ giá trị. Nếu giá trị này bằng hoặc nhỏ hơn n_bytes thì toàn bộ giá trị đã được sao chép. Tất cả n_bytes của bộ đệm đều được ghi: các byte còn lại được lấp đầy bởi các bản sao của bit dấu.

Nếu giá trị trả về lớn hơn n_bytes thì giá trị đó đã bị cắt bớt: càng nhiều bit thấp nhất của giá trị càng phù hợp sẽ được ghi và các bit cao hơn sẽ bị bỏ qua. Điều này phù hợp với hành vi điển hình của kiểu C-downcast.

Ghi chú

Tràn không được coi là một lỗi. Nếu giá trị trả về lớn hơn n_bytes thì hầu hết các bit quan trọng đều bị loại bỏ.

0 sẽ không bao giờ được trả lại.

Các giá trị luôn được sao chép dưới dạng phần bù hai.

Ví dụ sử dụng:

giá trị int32_t;
Py_ssize_t byte = PyLong_AsNativeBytes(pylong, &value, sizeof(value), -1);
nếu (byte < 0) {
    // Thất bại. Một ngoại lệ Python đã được đặt cùng với lý do.
    trả về NULL;
}
khác nếu (byte <= (Py_ssize_t)sizeof(value)) {
    // Thành công!
}
khác {
    // Đã xảy ra tràn, nhưng 'giá trị' chứa phần bị cắt bớt
    // bit thấp nhất của pylong.
}

Chuyển số 0 cho n_bytes sẽ trả về kích thước của bộ đệm đủ lớn để giữ giá trị. Điều này có thể lớn hơn mức cần thiết về mặt kỹ thuật, nhưng không phải là không hợp lý. Nếu n_bytes=0 thì buffer có thể là NULL.

Ghi chú

Truyền n_bytes=0 cho hàm này không phải là cách chính xác để xác định độ dài bit của giá trị.

Để lấy toàn bộ giá trị Python có kích thước không xác định, hàm có thể được gọi hai lần: đầu tiên để xác định kích thước bộ đệm, sau đó điền vào nó

// Hỏi chúng ta cần bao nhiêu dung lượng.
Py_ssize_t được mong đợi = PyLong_AsNativeBytes(pylong, NULL, 0, -1);
nếu (dự kiến < 0) {
    // Thất bại. Một ngoại lệ Python đã được đặt cùng với lý do.
    trả lại NULL;
}
khẳng định (dự kiến != 0);  // Không thể theo định nghĩa API.
uint8_t *bignum = malloc(dự kiến);
nếu (!bignum) {
    PyErr_SetString(PyExc_MemoryError, "bignum malloc không thành công.");
    trả về NULL;
}
// Lấy toàn bộ giá trị một cách an toàn.
Py_ssize_t byte = PyLong_AsNativeBytes(pylong, bignum, dự kiến, -1);
if (byte < 0) { // Ngoại lệ đã được đặt.
    miễn phí(bignum);
    trả lại NULL;
}
else if (bytes > Expected) { // Điều này không thể thực hiện được.
    PyErr_SetString(PyExc_RuntimeError,
        "Cắt bớt bignum bất ngờ sau khi kiểm tra kích thước.");
    miễn phí(bignum);
    trả về NULL;
}
// Thành công dự kiến dựa trên việc kiểm tra trước ở trên.
// ...dùng bignum...
miễn phí(bignum);

flags là -1 (Py_ASNATIVEBYTES_DEFAULTS) để chọn các giá trị mặc định hoạt động giống nhất với kiểu C hoặc kết hợp các cờ khác trong bảng bên dưới. Lưu ý rằng -1 không thể kết hợp với các cờ khác.

Hiện tại, -1 tương ứng với Py_ASNATIVEBYTES_NATIVE_ENDIAN | Py_ASNATIVEBYTES_UNSIGNED_BUFFER.

Lá cờ	Giá trị
Py_ASNATIVEBYTES_DEFAULTS¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`-1`
Py_ASNATIVEBYTES_BIG_ENDIAN¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`0`
Py_ASNATIVEBYTES_LITTLE_ENDIAN¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`1`
Py_ASNATIVEBYTES_NATIVE_ENDIAN¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`3`
Py_ASNATIVEBYTES_UNSIGNED_BUFFER¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`4`
Py_ASNATIVEBYTES_REJECT_NEGATIVE¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`8`
Py_ASNATIVEBYTES_ALLOW_INDEX¶ Một phần của ABI ổn định kể từ phiên bản 3.14.	`16`

Việc chỉ định Py_ASNATIVEBYTES_NATIVE_ENDIAN sẽ ghi đè bất kỳ cờ endian nào khác. Vượt qua 2 được bảo lưu.

Theo mặc định, bộ đệm đủ sẽ được yêu cầu bao gồm một bit dấu. Ví dụ: khi chuyển đổi 128 bằng n_bytes=1, hàm sẽ trả về 2 (hoặc nhiều hơn) để lưu trữ bit dấu 0.

Nếu Py_ASNATIVEBYTES_UNSIGNED_BUFFER được chỉ định, bit dấu 0 sẽ bị bỏ qua khi tính toán kích thước. Ví dụ, điều này cho phép 128 vừa với bộ đệm một byte. Nếu bộ đệm đích sau đó được coi là đã ký thì giá trị đầu vào dương có thể trở thành giá trị âm. Lưu ý rằng cờ không ảnh hưởng đến việc xử lý các giá trị âm: đối với những giá trị đó, khoảng trống cho bit dấu luôn được yêu cầu.

Việc chỉ định Py_ASNATIVEBYTES_REJECT_NEGATIVE sẽ đặt một ngoại lệ nếu pylong âm. Nếu không có cờ này, các giá trị âm sẽ được sao chép miễn là có đủ không gian cho ít nhất một bit dấu, bất kể Py_ASNATIVEBYTES_UNSIGNED_BUFFER có được chỉ định hay không.

Nếu Py_ASNATIVEBYTES_ALLOW_INDEX được chỉ định và một giá trị không nguyên được truyền, phương thức __index__() của nó sẽ được gọi đầu tiên. Điều này có thể dẫn đến việc thực thi mã Python và các luồng khác được phép chạy, điều này có thể gây ra những thay đổi đối với các đối tượng hoặc giá trị khác đang được sử dụng. Khi flags là -1, tùy chọn này không được đặt và các giá trị không nguyên sẽ tăng TypeError.

Ghi chú

Với flags mặc định (-1 hoặc UNSIGNED_BUFFER không có REJECT_NEGATIVE), nhiều số nguyên Python có thể ánh xạ tới một giá trị duy nhất mà không bị tràn. Ví dụ: cả 255 và -1 đều phù hợp với bộ đệm một byte và đặt tất cả các bit của nó. Điều này phù hợp với hành vi diễn viên C điển hình.

Added in version 3.13.

PyLong_AsPid(pid)¶

Macro để chuyển đổi số nguyên Python thành mã định danh quy trình.

Điều này có thể được định nghĩa là bí danh của PyLong_AsLong(), PyLong_FromLongLong() hoặc PyLong_AsInt(), tùy thuộc vào kích thước của loại PID của hệ thống.

Added in version 3.2.

int PyLong_GetSign(PyObject *obj, int *sign)¶

Lấy dấu của đối tượng số nguyên obj.

Nếu thành công, hãy đặt *sign thành dấu nguyên (0, -1 hoặc +1 cho số nguyên 0, âm hoặc dương tương ứng) và trả về 0.

Nếu thất bại, trả về -1 với một bộ ngoại lệ. Hàm này luôn thành công nếu obj là PyLongObject hoặc kiểu con của nó.

Added in version 3.14.

int PyLong_IsPositive(PyObject *obj)¶

Kiểm tra xem đối tượng số nguyên obj có dương không (obj > 0)

Nếu obj là một phiên bản của PyLongObject hoặc kiểu con của nó, hãy trả về 1 khi nó dương và 0 nếu ngược lại. Nếu không, hãy đặt ngoại lệ và trả về -1.

Added in version 3.14.

int PyLong_IsNegative(PyObject *obj)¶

Kiểm tra xem đối tượng số nguyên obj có âm (obj < 0) hay không.

Nếu obj là một phiên bản của PyLongObject hoặc kiểu con của nó, hãy trả về 1 khi nó âm và 0 nếu ngược lại. Nếu không, hãy đặt ngoại lệ và trả về -1.

Added in version 3.14.

int PyLong_IsZero(PyObject *obj)¶

Kiểm tra xem đối tượng số nguyên obj có bằng 0 không.

Nếu obj là một phiên bản của PyLongObject hoặc kiểu con của nó, hãy trả về 1 khi nó bằng 0 và 0 nếu ngược lại. Nếu không, hãy đặt ngoại lệ và trả về -1.

Added in version 3.14.

PyObject *PyLong_GetInfo(void)¶

Một phần của ABI ổn định.

Nếu thành công, hãy trả về named tuple chỉ đọc, chứa thông tin về cách biểu diễn số nguyên bên trong của Python. Xem sys.int_info để biết mô tả về từng trường riêng lẻ.

Nếu không thành công, hãy trả về NULL với một bộ ngoại lệ.

Added in version 3.1.

int PyUnstable_Long_IsCompact(const PyLongObject *op)¶

Đây là API không ổn định. Nó có thể thay đổi mà không có cảnh báo trong các bản phát hành nhỏ.

Trả về 1 nếu op nhỏ gọn, 0 nếu không.

Hàm này giúp mã quan trọng về hiệu năng có thể triển khai “đường dẫn nhanh” cho các số nguyên nhỏ. Đối với các giá trị nhỏ gọn, hãy sử dụng PyUnstable_Long_CompactValue(); đối với những người khác thì quay lại chức năng PyLong_As* hoặc PyLong_AsNativeBytes().

Việc tăng tốc dự kiến sẽ không đáng kể đối với hầu hết người dùng.

Chính xác những giá trị nào được coi là nhỏ gọn là chi tiết triển khai và có thể thay đổi.

Added in version 3.12.

Py_ssize_t PyUnstable_Long_CompactValue(const PyLongObject *op)¶

Đây là API không ổn định. Nó có thể thay đổi mà không có cảnh báo trong các bản phát hành nhỏ.

Nếu op nhỏ gọn, được xác định bởi PyUnstable_Long_IsCompact(), hãy trả về giá trị của nó.

Ngược lại, giá trị trả về không được xác định.

Added in version 3.12.

Xuất API¶

Added in version 3.14.

struct PyLongLayout¶

Bố cục của một mảng "chữ số" ("các chi" trong thuật ngữ GMP), được sử dụng để biểu thị giá trị tuyệt đối cho các số nguyên có độ chính xác tùy ý.

Sử dụng PyLong_GetNativeLayout() để lấy bố cục gốc của các đối tượng Python int, được sử dụng nội bộ cho các số nguyên có giá trị tuyệt đối "đủ lớn".

Xem thêm sys.int_info để biết thông tin tương tự trong Python.

uint8_t bits_per_digit¶: Bit trên mỗi chữ số. Ví dụ: chữ số 15 bit có nghĩa là các bit 0-14 chứa thông tin có ý nghĩa.

uint8_t digit_size¶: Kích thước chữ số tính bằng byte. Ví dụ: chữ số 15 bit sẽ yêu cầu ít nhất 2 byte.

int8_t digits_order¶

Thứ tự chữ số:

1 cho chữ số có nghĩa nhất đầu tiên
-1 cho chữ số có nghĩa nhỏ nhất đầu tiên

int8_t digit_endianness¶

Độ bền của chữ số:

1 cho byte quan trọng nhất đầu tiên (big endian)
-1 cho byte ít quan trọng nhất đầu tiên (endian nhỏ)

const PyLongLayout *PyLong_GetNativeLayout(void)¶

Nhận bố cục gốc của các đối tượng Python int.

Xem cấu trúc PyLongLayout.

Hàm không được gọi trước khi khởi tạo Python cũng như sau khi hoàn thiện Python. Bố cục trả về có hiệu lực cho đến khi Python được hoàn thiện. Bố cục giống nhau đối với tất cả các trình thông dịch phụ Python trong một quy trình và do đó nó có thể được lưu vào bộ đệm.

struct PyLongExport¶

Xuất đối tượng int Python.

Có hai trường hợp:

Nếu digits là NULL thì chỉ sử dụng thành viên value.
Nếu digits không phải là NULL, hãy sử dụng các thành viên negative, ndigits và digits.

int64_t value¶: Giá trị nguyên gốc của đối tượng int đã xuất. Chỉ hợp lệ nếu digits là NULL.

uint8_t negative¶: 1 nếu số âm, 0 nếu không. Chỉ hợp lệ nếu digits không phải là NULL.

Py_ssize_t ndigits¶: Số chữ số trong mảng digits. Chỉ hợp lệ nếu digits không phải là NULL.

const void *digits¶: Mảng chỉ đọc các chữ số không dấu. Có thể là NULL.

int PyLong_Export(PyObject *obj, PyLongExport *export_long)¶

Xuất đối tượng int Python.

export_long phải trỏ đến cấu trúc PyLongExport do người gọi phân bổ. Nó không được là NULL.

Nếu thành công, hãy điền *export_long và trả về 0. Nếu có lỗi, hãy đặt ngoại lệ và trả về -1.

PyLong_FreeExport() phải được gọi khi việc xuất không còn cần thiết nữa.

Hàm này luôn thành công nếu obj là đối tượng int của Python hoặc một lớp con.

void PyLong_FreeExport(PyLongExport *export_long)¶: Phát hành export_long xuất được tạo bởi PyLong_Export().

Gọi PyLong_FreeExport() là tùy chọn nếu export_long->digits là NULL.

PyLongWriter API¶

PyLongWriter API có thể được sử dụng để nhập số nguyên.

Added in version 3.14.

struct PyLongWriter¶

Một phiên bản trình soạn thảo Python int.

Phiên bản phải bị hủy bởi PyLongWriter_Finish() hoặc PyLongWriter_Discard().

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

Tạo một PyLongWriter.

Nếu thành công, hãy phân bổ *digits và trả về một nhà văn. Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

negative là 1 nếu số âm, hoặc 0 nếu ngược lại.

ndigits là số chữ số trong mảng digits. Nó phải lớn hơn 0.

digits không được là NULL.

Sau khi gọi hàm này thành công, người gọi phải điền vào mảng chữ số digits rồi gọi PyLongWriter_Finish() để nhận Python int. Bố cục của digits được mô tả bởi PyLong_GetNativeLayout().

Các chữ số phải nằm trong phạm vi [0; (1 << bits_per_digit) - 1] (trong đó bits_per_digit là số bit trên mỗi chữ số). Mọi chữ số quan trọng nhất chưa được sử dụng phải được đặt thành 0.

Ngoài ra, hãy gọi PyLongWriter_Discard() để hủy phiên bản trình ghi mà không tạo đối tượng int.

PyObject *PyLongWriter_Finish(PyLongWriter *writer)¶

Giá trị trả về: Tham chiếu mới.

Hoàn thành PyLongWriter được tạo bởi PyLongWriter_Create().

Nếu thành công, hãy trả về một đối tượng Python int. Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

Hàm đảm nhiệm việc chuẩn hóa các chữ số và chuyển đổi đối tượng thành số nguyên nhỏ gọn nếu cần.

Phiên bản người ghi và mảng digits không hợp lệ sau lệnh gọi.

void PyLongWriter_Discard(PyLongWriter *writer)¶

Loại bỏ PyLongWriter được tạo bởi PyLongWriter_Create().

Nếu writer là NULL thì không có thao tác nào được thực hiện.

Phiên bản người ghi và mảng digits không hợp lệ sau lệnh gọi.

API không được dùng nữa¶

Các macro này là soft deprecated. Chúng mô tả các tham số biểu diễn bên trong của các phiên bản PyLongObject.

Thay vào đó, hãy sử dụng PyLong_GetNativeLayout() cùng với PyLong_Export() để đọc dữ liệu số nguyên hoặc PyLongWriter để ghi dữ liệu đó. Chúng hiện sử dụng cùng một bố cục nhưng được thiết kế để tiếp tục hoạt động chính xác ngay cả khi biểu diễn số nguyên bên trong của CPython thay đổi.

PyLong_SHIFT¶: Điều này tương đương với bits_per_digit ở đầu ra của PyLong_GetNativeLayout().

PyLong_BASE¶: Điều này hiện tương đương với 1 << PyLong_SHIFT.

PyLong_MASK¶: Điều này hiện tương đương với (1 << PyLong_SHIFT) - 1

Đối tượng số nguyên¶

Xuất API¶

PyLongWriter API¶

API không được dùng nữa¶

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này