Đối tượng byte

Các hàm này tăng TypeError khi mong đợi tham số byte và được gọi với tham số không phải byte.

type PyBytesObject

Kiểu con này của PyObject đại diện cho một đối tượng byte Python.

PyTypeObject PyBytes_Type

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

Phiên bản PyTypeObject này đại diện cho loại byte Python; nó là đối tượng tương tự như bytes trong lớp Python.

int PyBytes_Check(PyObject *o)

Trả về true nếu đối tượng o là đối tượng byte hoặc một thể hiện của kiểu con của kiểu byte. Chức năng này luôn thành công.

int PyBytes_CheckExact(PyObject *o)

Trả về true nếu đối tượng o là đối tượng byte, nhưng không phải là phiên bản của kiểu con của kiểu byte. Chức năng này luôn thành công.

PyObject *PyBytes_FromString(const char *v)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Atomic.

Trả về một đối tượng bytes mới với một bản sao của chuỗi v làm giá trị nếu thành công và NULL nếu thất bại. Tham số v không được là NULL; nó sẽ không được kiểm tra.

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Atomic.

Trả về một đối tượng byte mới với một bản sao của chuỗi v làm giá trị và độ dài len nếu thành công và NULL nếu thất bại. Nếu v là NULL, nội dung của đối tượng byte chưa được khởi tạo.

PyObject *PyBytes_FromFormat(const char *format, ...)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Atomic.

Lấy một chuỗi C printf()-style format và một số đối số thay đổi, tính kích thước của đối tượng byte Python thu được và trả về một đối tượng bytes với các giá trị được định dạng trong đó. Các đối số của biến phải là loại C và phải tương ứng chính xác với các ký tự định dạng trong chuỗi format. Các ký tự định dạng sau được cho phép:

Định dạng ký tự	Kiểu	Bình luận
%%	n/a	Ký tự % theo nghĩa đen.
%c	int	Một byte đơn, được biểu diễn dưới dạng C int.
%d	int	Tương đương với printf("%d"). [1]
%u	int không dấu	Tương đương với printf("%u"). [1]
%ld	dài	Tương đương với printf("%ld"). [1]
%lu	dài không dấu	Tương đương với printf("%lu"). [1]
%zd	Py_ssize_t	Tương đương với printf("%zd"). [1]
%zu	kích thước_t	Tương đương với printf("%zu"). [1]
%i	int	Tương đương với printf("%i"). [1]
%x	int	Tương đương với printf("%x"). [1]
%s	const char*	Một mảng ký tự C kết thúc bằng null.
%p	const void*	Biểu diễn hex của con trỏ C. Hầu hết tương đương với printf("%p") ngoại trừ việc nó được đảm bảo bắt đầu bằng 0x theo nghĩa đen bất kể printf của nền tảng mang lại kết quả gì.

Ký tự định dạng không được nhận dạng sẽ khiến tất cả phần còn lại của chuỗi định dạng được sao chép nguyên trạng vào đối tượng kết quả và mọi đối số bổ sung sẽ bị loại bỏ.

[1] (1,2,3,4,5,6,7,8)

Đối với các chỉ định số nguyên (d, u, ld, lu, zd, zu, i, x): cờ chuyển đổi 0 có hiệu lực ngay cả khi độ chính xác được đưa ra.

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Atomic.

Giống hệt PyBytes_FromFormat() ngoại trừ việc nó nhận chính xác hai đối số.

PyObject *PyBytes_FromObject(PyObject *o)

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định. Thread safety: Safe for concurrent use on the same object.

Trả về biểu diễn byte của đối tượng o thực hiện giao thức bộ đệm.

Ghi chú

Nếu đối tượng thực hiện giao thức bộ đệm thì bộ đệm không được bị thay đổi trong khi đối tượng byte đang được tạo.

Py_ssize_t PyBytes_Size(PyObject *o)

Một phần của ABI ổn định. Thread safety: Atomic.

Trả về độ dài của byte trong đối tượng byte o.

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

Thread safety: Atomic.

Tương tự như PyBytes_Size() nhưng không có tính năng kiểm tra lỗi.

char *PyBytes_AsString(PyObject *o)

Một phần của ABI ổn định. Thread safety: Safe to call from multiple threads with external synchronization only.

Trả về con trỏ tới nội dung của o. Con trỏ đề cập đến bộ đệm bên trong của o, bao gồm các byte len(o) + 1. Byte cuối cùng trong bộ đệm luôn là null, bất kể có byte null nào khác hay không. Dữ liệu không được sửa đổi theo bất kỳ cách nào, trừ khi đối tượng vừa được tạo bằng PyBytes_FromStringAndSize(NULL, size). Nó không được phép giải phóng. Nếu o hoàn toàn không phải là một đối tượng byte, PyBytes_AsString() trả về NULL và tăng TypeError.

char *PyBytes_AS_STRING(PyObject *string)

Thread safety: Safe to call from multiple threads with external synchronization only.

Tương tự như PyBytes_AsString() nhưng không có tính năng kiểm tra lỗi.

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

Một phần của ABI ổn định. Thread safety: Safe to call from multiple threads with external synchronization only.

Trả về nội dung kết thúc null của đối tượng obj thông qua các biến đầu ra buffer và length. Trả về 0 khi thành công.

Nếu length là NULL, đối tượng byte có thể không chứa byte rỗng được nhúng; nếu đúng như vậy, hàm sẽ trả về -1 và ValueError sẽ được nâng lên.

Bộ đệm đề cập đến bộ đệm bên trong của obj, bao gồm một byte rỗng bổ sung ở cuối (không được tính trong length). Dữ liệu không được sửa đổi theo bất kỳ cách nào, trừ khi đối tượng vừa được tạo bằng PyBytes_FromStringAndSize(NULL, size). Nó không được phép giải phóng. Nếu obj hoàn toàn không phải là một đối tượng byte, PyBytes_AsStringAndSize() trả về -1 và tăng TypeError.

Thay đổi trong phiên bản 3.5: Trước đây, TypeError đã được đưa ra khi gặp phải các byte rỗng được nhúng trong đối tượng byte.

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

Một phần của ABI ổn định. Thread safety: Safe for concurrent use on the same object.

Tạo một đối tượng byte mới trong *bytes chứa nội dung của newpart được thêm vào bytes; người gọi sẽ sở hữu tài liệu tham khảo mới. Tham chiếu đến giá trị cũ của bytes sẽ bị đánh cắp. Nếu không thể tạo đối tượng mới, tham chiếu cũ tới bytes sẽ vẫn bị loại bỏ và giá trị của *bytes sẽ được đặt thành NULL; ngoại lệ thích hợp sẽ được thiết lập.

Ghi chú

Nếu newpart triển khai giao thức bộ đệm thì bộ đệm không được bị thay đổi trong khi đối tượng byte mới đang được tạo.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

Một phần của ABI ổn định. Thread safety: Safe for concurrent use on the same object.

Tạo một đối tượng byte mới trong *bytes chứa nội dung của newpart được thêm vào bytes. Phiên bản này phát hành strong reference thành newpart (tức là giảm số lượng tham chiếu của nó).

Ghi chú

Nếu newpart triển khai giao thức bộ đệm thì bộ đệm không được bị thay đổi trong khi đối tượng byte mới đang được tạo.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)

Thread safety: Safe for concurrent use on the same object.

Tương tự như sep.join(iterable) trong Python.

sep phải là đối tượng bytes của Python. (Lưu ý rằng PyUnicode_Join() chấp nhận dấu phân cách NULL và coi nó là khoảng trắng, trong khi PyBytes_Join() không chấp nhận dấu phân cách NULL.)

iterable phải là một đối tượng có thể lặp lại tạo ra các đối tượng triển khai buffer protocol.

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

Added in version 3.14.

Ghi chú

Nếu các đối tượng iterable triển khai giao thức bộ đệm thì bộ đệm không được bị thay đổi trong khi đối tượng byte mới đang được tạo.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

Thread safety: Safe to call without external synchronization on distinct objects.

Thay đổi kích thước một đối tượng byte. newsize sẽ là độ dài mới của đối tượng byte. Bạn có thể coi nó như việc tạo một đối tượng byte mới và hủy đối tượng cũ, chỉ hiệu quả hơn. Truyền địa chỉ của một đối tượng byte hiện có dưới dạng giá trị lvalue (nó có thể được ghi vào) và kích thước mới mong muốn. Nếu thành công, *bytes giữ đối tượng byte đã thay đổi kích thước và 0 được trả về; địa chỉ trong *bytes có thể khác với giá trị đầu vào của nó. Nếu việc phân bổ lại không thành công, đối tượng byte ban đầu tại *bytes sẽ bị hủy phân bổ, *bytes được đặt thành NULL, MemoryError được đặt và -1 được trả về.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)

Một phần của ABI ổn định. Thread safety: Atomic.

Lấy biểu diễn chuỗi của bytes. Hàm này hiện được sử dụng để triển khai bytes.__repr__() trong Python.

Hàm này không thực hiện kiểm tra kiểu; hành vi không xác định là chuyển bytes dưới dạng đối tượng không phải byte hoặc NULL.

Nếu smartquotes là đúng, thì cách biểu diễn sẽ sử dụng chuỗi trích dẫn kép thay vì chuỗi trích dẫn đơn khi có dấu ngoặc đơn trong bytes. Ví dụ: chuỗi byte 'Python' sẽ được biểu diễn dưới dạng b"'Python'" khi smartquotes là đúng hoặc b'\'Python\'' khi nó sai.

Nếu thành công, hàm này trả về strong reference cho đối tượng str chứa biểu diễn. Nếu thất bại, điều này sẽ trả về NULL với một bộ ngoại lệ.

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)

Một phần của ABI ổn định. Thread safety: Atomic.

Bỏ thoát chuỗi thoát dấu gạch chéo ngược s. s không được là NULL. len phải có kích thước bằng s.

errors phải là một trong "strict", "replace" hoặc "ignore". Nếu errors là NULL thì "strict" được sử dụng theo mặc định.

Nếu thành công, hàm này trả về strong reference cho đối tượng bytes của Python chứa chuỗi không thoát. Nếu thất bại, hàm này trả về NULL với một bộ ngoại lệ.

Thay đổi trong phiên bản 3.9: unicode và recode_encoding hiện không được sử dụng.