Đối tượng và Codec Unicode¶

Đối tượng Unicode¶

Kể từ khi triển khai PEP 393 trong Python 3.3, các đối tượng Unicode sử dụng nội bộ nhiều cách biểu diễn khác nhau để cho phép xử lý toàn bộ phạm vi ký tự Unicode trong khi vẫn duy trì hiệu quả bộ nhớ. Có những trường hợp đặc biệt đối với các chuỗi trong đó tất cả các điểm mã đều dưới 128, 256 hoặc 65536; nếu không, điểm mã phải dưới 1114112 (là phạm vi Unicode đầy đủ).

Biểu diễn UTF-8 được tạo theo yêu cầu và được lưu vào bộ đệm trong đối tượng Unicode.

Ghi chú

Bản trình bày Py_UNICODE đã bị xóa kể từ Python 3.12 với các API không được dùng nữa. Xem PEP 623 để biết thêm thông tin.

Loại Unicode¶

Đây là các loại đối tượng Unicode cơ bản được sử dụng để triển khai Unicode trong Python:

PyTypeObject PyUnicode_Type¶: Một phần của ABI ổn định.
Phiên bản PyTypeObject này đại diện cho loại Python Unicode. Nó được hiển thị với mã Python dưới dạng str.

PyTypeObject PyUnicodeIter_Type¶: Một phần của ABI ổn định.
Phiên bản PyTypeObject này đại diện cho kiểu trình lặp Python Unicode. Nó được sử dụng để lặp lại các đối tượng chuỗi Unicode.

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: Một phần của ABI ổn định.
Các loại này là typedefs cho các loại số nguyên không dấu đủ rộng để chứa các ký tự lần lượt là 32 bit, 16 bit và 8 bit. Khi xử lý các ký tự Unicode đơn, hãy sử dụng Py_UCS4.

Added in version 3.3.

type PyASCIIObject¶

type PyCompactUnicodeObject¶

type PyUnicodeObject¶

Các kiểu con này của PyObject đại diện cho một đối tượng Python Unicode. Trong hầu hết các trường hợp, chúng không nên được sử dụng trực tiếp, vì tất cả các hàm API xử lý các đối tượng Unicode đều nhận và trả về các con trỏ PyObject.

Added in version 3.3.

Cấu trúc của một đối tượng cụ thể có thể được xác định bằng cách sử dụng các macro sau. Các macro không thể bị lỗi; hành vi của chúng không được xác định nếu đối số của chúng không phải là đối tượng Python Unicode.

PyUnicode_IS_COMPACT(o)¶: Đúng nếu o sử dụng cấu trúc PyCompactUnicodeObject.

Added in version 3.3.

PyUnicode_IS_COMPACT_ASCII(o)¶: Đúng nếu o sử dụng cấu trúc PyASCIIObject.

Added in version 3.3.

Các API sau là macro C và các hàm nội tuyến tĩnh để kiểm tra nhanh và truy cập vào dữ liệu chỉ đọc nội bộ của các đối tượng Unicode:

int PyUnicode_Check(PyObject *obj)¶: Trả về true nếu đối tượng obj là đối tượng Unicode hoặc một phiên bản của kiểu con Unicode. Chức năng này luôn thành công.

int PyUnicode_CheckExact(PyObject *obj)¶: Trả về true nếu đối tượng obj là đối tượng Unicode nhưng không phải là phiên bản của kiểu con. Chức năng này luôn thành công.

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)¶: Trả về độ dài của chuỗi Unicode, tính bằng điểm mã. unicode phải là một đối tượng Unicode ở dạng "chuẩn" (không được chọn).

Added in version 3.3.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)¶
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)¶
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)¶: Trả về một con trỏ tới biểu diễn chuẩn được chuyển thành các kiểu số nguyên UCS1, UCS2 hoặc UCS4 để truy cập ký tự trực tiếp. Không có kiểm tra nào được thực hiện nếu biểu diễn chuẩn có kích thước ký tự chính xác; sử dụng PyUnicode_KIND() để chọn chức năng phù hợp.

Added in version 3.3.

PyUnicode_1BYTE_KIND¶
PyUnicode_2BYTE_KIND¶
PyUnicode_4BYTE_KIND¶: Trả về giá trị của macro PyUnicode_KIND().

Added in version 3.3.

Thay đổi trong phiên bản 3.12: PyUnicode_WCHAR_KIND đã bị xóa.

int PyUnicode_KIND(PyObject *unicode)¶: Trả về một trong các hằng số loại PyUnicode (xem ở trên) cho biết đối tượng Unicode này sử dụng bao nhiêu byte cho mỗi ký tự để lưu trữ dữ liệu của nó. unicode phải là một đối tượng Unicode ở dạng "chuẩn" (không được chọn).

Added in version 3.3.

void *PyUnicode_DATA(PyObject *unicode)¶: Trả về một con trỏ void cho bộ đệm Unicode thô. unicode phải là một đối tượng Unicode ở dạng "chuẩn" (không được chọn).

Added in version 3.3.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)¶

Viết điểm mã value vào index dựa trên số 0 đã cho trong một chuỗi.

Giá trị kind và con trỏ data phải được lấy từ một chuỗi sử dụng PyUnicode_KIND() và PyUnicode_DATA() tương ứng. Bạn phải giữ một tham chiếu đến chuỗi đó trong khi gọi PyUnicode_WRITE(). Tất cả các yêu cầu của PyUnicode_WriteChar() cũng được áp dụng.

Hàm này không thực hiện kiểm tra bất kỳ yêu cầu nào của nó và được thiết kế để sử dụng trong các vòng lặp.

Added in version 3.3.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)¶: Đọc điểm mã từ biểu diễn chuẩn data (như thu được bằng PyUnicode_DATA()). Không có kiểm tra hoặc cuộc gọi sẵn sàng được thực hiện.

Added in version 3.3.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)¶: Đọc một ký tự từ đối tượng Unicode unicode, ký tự này phải ở dạng biểu diễn "chuẩn". Điều này kém hiệu quả hơn PyUnicode_READ() nếu bạn thực hiện nhiều lần đọc liên tiếp.

Added in version 3.3.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)¶: Trả về điểm mã tối đa phù hợp để tạo một chuỗi khác dựa trên unicode, chuỗi này phải ở dạng biểu diễn "chuẩn". Đây luôn là một phép tính gần đúng nhưng hiệu quả hơn việc lặp qua chuỗi.

Added in version 3.3.

int PyUnicode_IsIdentifier(PyObject *unicode)¶: Một phần của ABI ổn định.
Trả về 1 nếu chuỗi là mã định danh hợp lệ theo định nghĩa ngôn ngữ, phần Tên (số nhận dạng và từ khóa). Trả về 0 nếu không.

Thay đổi trong phiên bản 3.9: Hàm không gọi Py_FatalError() nữa nếu chuỗi chưa sẵn sàng.

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶: Trả về true nếu chuỗi chỉ chứa các ký tự ASCII. Tương đương với str.isascii().

Added in version 3.2.

Thuộc tính ký tự Unicode¶

Unicode cung cấp nhiều thuộc tính ký tự khác nhau. Những thứ cần thiết nhất có sẵn thông qua các macro này được ánh xạ tới các hàm C tùy thuộc vào cấu hình Python.

int Py_UNICODE_ISSPACE(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự khoảng trắng hay không.

int Py_UNICODE_ISLOWER(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự viết thường hay không.

int Py_UNICODE_ISUPPER(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự viết hoa hay không.

int Py_UNICODE_ISTITLE(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự tiêu đề hay không.

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự ngắt dòng hay không.

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự thập phân hay không.

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự chữ số hay không.

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự số hay không.

int Py_UNICODE_ISALPHA(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự chữ cái hay không.

int Py_UNICODE_ISALNUM(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự chữ và số hay không.

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)¶: Trả về 1 hoặc 0 tùy thuộc vào việc ch có phải là ký tự in được hay không, theo nghĩa str.isprintable().

Các API này có thể được sử dụng để chuyển đổi ký tự trực tiếp nhanh chóng:

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành chữ thường.

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành chữ hoa.

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành chữ hoa chữ thường.

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành số nguyên dương thập phân. Trả về -1 nếu điều này không thể thực hiện được. Chức năng này không đưa ra ngoại lệ.

int Py_UNICODE_TODIGIT(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành số nguyên có một chữ số. Trả về -1 nếu điều này không thể thực hiện được. Chức năng này không đưa ra ngoại lệ.

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)¶: Trả về ký tự ch được chuyển đổi thành double. Trả về -1.0 nếu điều này không thể thực hiện được. Chức năng này không đưa ra ngoại lệ.

Các API này có thể được sử dụng để hoạt động với các đại diện:

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)¶: Kiểm tra xem ch có phải là người thay thế (0xD800 <= ch <= 0xDFFF) không.

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)¶: Kiểm tra xem ch có phải là đại diện thay thế cao không (0xD800 <= ch <= 0xDBFF)

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)¶: Kiểm tra xem ch có phải là đại diện thay thế thấp (0xDC00 <= ch <= 0xDFFF) hay không.

Py_UCS4 Py_UNICODE_HIGH_SURROGATE(Py_UCS4 ch)¶: Trả về giá trị thay thế UTF-16 cao (0xD800 đến 0xDBFF) cho điểm mã Unicode trong phạm vi [0x10000; 0x10FFFF].

Py_UCS4 Py_UNICODE_LOW_SURROGATE(Py_UCS4 ch)¶: Trả về giá trị thay thế UTF-16 thấp (0xDC00 đến 0xDFFF) cho điểm mã Unicode trong phạm vi [0x10000; 0x10FFFF].

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)¶: Kết hợp hai điểm mã thay thế và trả về một giá trị Py_UCS4 duy nhất. high và low lần lượt là các đại diện thay thế hàng đầu và cuối cùng trong một cặp thay thế. high phải nằm trong phạm vi [0xD800; 0xDBFF] và low phải nằm trong phạm vi [0xDC00; 0xDFFF].

Tạo và truy cập chuỗi Unicode¶

Để tạo các đối tượng Unicode và truy cập các thuộc tính chuỗi cơ bản của chúng, hãy sử dụng các API sau:

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)¶

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

Tạo một đối tượng Unicode mới. maxchar phải là điểm mã tối đa thực sự được đặt trong chuỗi. Dưới dạng gần đúng, nó có thể được làm tròn đến giá trị gần nhất trong dãy 127, 255, 65535, 1114111.

Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

Sau khi tạo, chuỗi có thể được điền bằng PyUnicode_WriteChar(), PyUnicode_CopyCharacters(), PyUnicode_Fill(), PyUnicode_WRITE() hoặc tương tự. Vì các chuỗi được cho là không thể thay đổi nên hãy cẩn thận để không “sử dụng” kết quả trong khi nó đang được sửa đổi. Cụ thể, trước khi nó chứa đầy nội dung cuối cùng, một chuỗi:

không được băm,
không được là converted to UTF-8 hoặc một cách thể hiện không "chuẩn" khác,
không được thay đổi số tham chiếu của nó,
không được chia sẻ với mã có thể thực hiện một trong những điều trên.

Danh sách này không đầy đủ. Trách nhiệm của bạn là tránh những việc sử dụng này; Python không phải lúc nào cũng kiểm tra các yêu cầu này.

Để tránh vô tình làm lộ đối tượng chuỗi được viết một phần, hãy ưu tiên sử dụng PyUnicodeWriter API hoặc một trong các hàm PyUnicode_From* bên dưới.

Added in version 3.3.

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)¶

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

Tạo một đối tượng Unicode mới với kind đã cho (các giá trị có thể là PyUnicode_1BYTE_KIND, v.v., được trả về bởi PyUnicode_KIND()). Zz003zz phải trỏ đến một mảng đơn vị size gồm 1, 2 hoặc 4 byte cho mỗi ký tự, tùy theo loại.

Nếu cần, buffer đầu vào sẽ được sao chép và chuyển đổi thành biểu diễn chuẩn. Ví dụ: nếu buffer là chuỗi UCS4 (PyUnicode_4BYTE_KIND) và nó chỉ bao gồm các điểm mã trong phạm vi UCS1, thì nó sẽ được chuyển thành UCS1 (PyUnicode_1BYTE_KIND).

Added in version 3.3.

PyObject *PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)¶

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

Tạo một đối tượng Unicode từ bộ đệm char str. Các byte sẽ được hiểu là được mã hóa UTF-8. Bộ đệm được sao chép vào đối tượng mới. Giá trị trả về có thể là một đối tượng được chia sẻ, tức là không được phép sửa đổi dữ liệu.

Hàm này tăng SystemError khi:

size < 0,
str là NULL và size > 0

Thay đổi trong phiên bản 3.12: str == NULL với size > 0 không được phép nữa.

PyObject *PyUnicode_FromString(const char *str)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode từ bộ đệm char kết thúc null được mã hóa UTF-8 str.

PyObject *PyUnicode_FromFormat(const char *format, ...)¶

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

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 chuỗi Unicode Python thu được và trả về một chuỗi có 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 được mã hóa format ASCII.

Công cụ xác định chuyển đổi chứa hai ký tự trở lên và có các thành phần sau, phải xuất hiện theo thứ tự sau:

Ký tự '%', đánh dấu sự bắt đầu của bộ xác định.
Cờ chuyển đổi (tùy chọn), ảnh hưởng đến kết quả của một số loại chuyển đổi.
Độ rộng trường tối thiểu (tùy chọn). Nếu được chỉ định là '*' (dấu hoa thị), thì chiều rộng thực tế sẽ được đưa ra trong đối số tiếp theo, phải thuộc loại int và đối tượng cần chuyển đổi sẽ xuất hiện sau độ rộng trường tối thiểu và độ chính xác tùy chọn.
Độ chính xác (tùy chọn), được cung cấp dưới dạng '.' (dấu chấm) theo sau là độ chính xác. Nếu được chỉ định là '*' (dấu hoa thị), độ chính xác thực tế sẽ được đưa ra trong đối số tiếp theo, đối số này phải thuộc loại int và giá trị cần chuyển đổi sẽ xuất hiện sau độ chính xác.
Công cụ sửa đổi độ dài (tùy chọn).
Loại chuyển đổi.

Các ký tự cờ chuyển đổi là:

Lá cờ	Nghĩa
`0`	Việc chuyển đổi sẽ được đệm bằng 0 đối với các giá trị số.
`-`	Giá trị chuyển đổi được điều chỉnh trái (ghi đè cờ `0` nếu cả hai đều được đưa ra).

Công cụ sửa đổi độ dài cho các chuyển đổi số nguyên sau (d, i, o, u, x hoặc X) chỉ định loại đối số (int theo mặc định):

Công cụ sửa đổi	Các loại
`l`	long hoặc unsigned long
`ll`	long long hoặc unsigned long long
`j`	`intmax_t` hoặc `uintmax_t`
`z`	`size_t` hoặc `ssize_t`
`t`	`ptrdiff_t`

Công cụ sửa đổi độ dài l cho các chuyển đổi sau s hoặc V chỉ định rằng loại đối số là const wchar_t*.

Các chỉ định chuyển đổi là:

Công cụ xác định chuyển đổi	Kiểu	Bình luận
`%`	n/a	Ký tự `%` theo nghĩa đen.
`d`, `i`	Được chỉ định bởi công cụ sửa đổi độ dài	Biểu diễn thập phân của số nguyên C có dấu.
`u`	Được chỉ định bởi công cụ sửa đổi độ dài	Biểu diễn thập phân của số nguyên C không dấu.
`o`	Được chỉ định bởi công cụ sửa đổi độ dài	Biểu diễn bát phân của số nguyên C không dấu.
`x`	Được chỉ định bởi công cụ sửa đổi độ dài	Biểu diễn thập lục phân của số nguyên C không dấu (chữ thường).
`X`	Được chỉ định bởi công cụ sửa đổi độ dài	Biểu diễn thập lục phân của số nguyên C không dấu (chữ hoa).
`c`	int	Một nhân vật duy nhất.
`s`	const char* hoặc const wchar_t*	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ì.
`A`	PyObject*	Kết quả gọi `ascii()`.
`U`	PyObject*	Một đối tượng Unicode.
`V`	PyObject, const char hoặc const wchar_t*	Một đối tượng Unicode (có thể là `NULL`) và mảng ký tự C kết thúc bằng null làm tham số thứ hai (sẽ được sử dụng nếu tham số đầu tiên là `NULL`).
`S`	PyObject*	Kết quả gọi `PyObject_Str()`.
`R`	PyObject*	Kết quả gọi `PyObject_Repr()`.
`T`	PyObject*	Lấy tên đầy đủ của một loại đối tượng; gọi `PyType_GetFullyQualifiedName()`.
`#T`	PyObject*	Tương tự như định dạng `T`, nhưng sử dụng dấu hai chấm (`:`) làm dấu phân cách giữa tên mô-đun và tên đủ điều kiện.
`N`	PyTypeObject*	Lấy tên đầy đủ của một loại; gọi `PyType_GetFullyQualifiedName()`.
`#N`	PyTypeObject*	Tương tự như định dạng `N`, nhưng sử dụng dấu hai chấm (`:`) làm dấu phân cách giữa tên mô-đun và tên đủ điều kiện.

Ghi chú

Đơn vị định dạng chiều rộng là số ký tự chứ không phải byte. Đơn vị định dạng chính xác là số byte hoặc mục wchar_t (nếu sử dụng công cụ sửa đổi độ dài l) cho "%s" và "%V" (nếu đối số PyObject* là NULL) và một số ký tự cho "%A", "%U", "%S", "%R" và "%V" (nếu đối số PyObject* không phải là NULL).

Ghi chú

Không giống như C printf(), cờ 0 có hiệu lực ngay cả khi độ chính xác được đưa ra cho các chuyển đổi số nguyên (d, i, u, o, x hoặc X).

Thay đổi trong phiên bản 3.2: Đã thêm hỗ trợ cho "%lld" và "%llu".

Thay đổi trong phiên bản 3.3: Đã thêm hỗ trợ cho "%li", "%lli" và "%zi".

Thay đổi trong phiên bản 3.4: Hỗ trợ định dạng chiều rộng và độ chính xác cho "%s", "%A", "%U", "%V", "%S", "%R".

Thay đổi trong phiên bản 3.12: Hỗ trợ các chỉ định chuyển đổi o và X. Hỗ trợ các bộ sửa đổi độ dài j và t. Công cụ sửa đổi độ dài hiện được áp dụng cho tất cả các chuyển đổi số nguyên. Công cụ sửa đổi độ dài l hiện được áp dụng cho các công cụ xác định chuyển đổi s và V. Hỗ trợ độ rộng thay đổi và độ chính xác *. Hỗ trợ cờ -.

Ký tự định dạng không được nhận dạng hiện đặt SystemError. Trong các phiên bản trước, nó 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 chuỗi kết quả và mọi đối số bổ sung sẽ bị loại bỏ.

Thay đổi trong phiên bản 3.13: Đã thêm hỗ trợ cho các định dạng %T, %#T, %N và %#N.

PyObject *PyUnicode_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.
Giống hệt PyUnicode_FromFormat() ngoại trừ việc nó nhận chính xác hai đối số.

PyObject *PyUnicode_FromObject(PyObject *obj)¶

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

Sao chép một thể hiện của kiểu con Unicode sang một đối tượng Unicode thực sự mới nếu cần. Nếu obj đã là một đối tượng Unicode thực sự (không phải kiểu con), hãy trả về một strong reference mới cho đối tượng.

Các đối tượng không phải Unicode hoặc các kiểu con của nó sẽ gây ra TypeError.

PyObject *PyUnicode_FromOrdinal(int ordinal)¶

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

Tạo một đối tượng Unicode từ điểm mã Unicode đã cho ordinal.

Thứ tự phải ở dạng range(0x110000). Một ValueError được nêu ra trong trường hợp không phải vậy.

PyObject *PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)¶

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

Giải mã đối tượng được mã hóa obj thành đối tượng Unicode.

bytes, bytearray và bytes-like objects khác được giải mã theo encoding đã cho và sử dụng cách xử lý lỗi được xác định bởi errors. Cả hai đều có thể là NULL để giao diện sử dụng các giá trị mặc định (xem Codec tích hợp để biết chi tiết).

Tất cả các đối tượng khác, bao gồm cả các đối tượng Unicode, đều đặt TypeError.

API trả về NULL nếu có lỗi. Người gọi có trách nhiệm khai báo các đối tượng được trả về.

void PyUnicode_Append(PyObject **p_left, PyObject *right)¶

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

Nối chuỗi right vào cuối p_left. p_left phải trỏ tới strong reference tới một đối tượng Unicode; PyUnicode_Append() phát hành ("đánh cắp") tài liệu tham khảo này.

Nếu có lỗi, hãy đặt *p_left thành NULL và đặt một ngoại lệ.

Nếu thành công, hãy đặt *p_left thành một tham chiếu mạnh mới cho kết quả.

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶: Một phần của ABI ổn định.
Chức năng này tương tự như PyUnicode_Append(), với điểm khác biệt duy nhất là nó giảm số lượng tham chiếu của right đi một.

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về ánh xạ phù hợp để giải mã mã hóa một byte tùy chỉnh. Cho một chuỗi Unicode string có tối đa 256 ký tự biểu thị một bảng mã hóa, trả về một đối tượng ánh xạ bên trong nhỏ gọn hoặc một thứ tự ký tự ánh xạ từ điển thành các giá trị byte. Tăng TypeError và trả về NULL khi đầu vào không hợp lệ.

Added in version 3.2.

const char *PyUnicode_GetDefaultEncoding(void)¶

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

Trả về tên của mã hóa chuỗi mặc định, "utf-8". Xem sys.getdefaultencoding().

Chuỗi trả về không cần phải giải phóng và có hiệu lực cho đến khi trình thông dịch tắt.

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)¶

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

Trả về độ dài của đối tượng Unicode, tính bằng điểm mã.

Nếu có lỗi, hãy đặt ngoại lệ và trả về -1.

Added in version 3.3.

Py_ssize_t PyUnicode_CopyCharacters(PyObject *to, Py_ssize_t to_start, PyObject *from, Py_ssize_t from_start, Py_ssize_t how_many)¶

Sao chép các ký tự từ một đối tượng Unicode sang một đối tượng khác. Hàm này thực hiện chuyển đổi ký tự khi cần thiết và quay trở lại memcpy() nếu có thể. Trả về -1 và đặt một ngoại lệ nếu có lỗi, nếu không thì trả về số lượng ký tự được sao chép.

Chuỗi này phải chưa được “sử dụng”. Xem PyUnicode_New() để biết chi tiết.

Added in version 3.3.

int PyUnicode_Resize(PyObject **unicode, Py_ssize_t length);¶

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

Thay đổi kích thước đối tượng Unicode *unicode thành length mới trong điểm mã.

Cố gắng thay đổi kích thước chuỗi tại chỗ (thường nhanh hơn việc cấp phát một chuỗi mới và sao chép các ký tự) hoặc tạo một chuỗi mới.

*unicode được sửa đổi để trỏ đến đối tượng mới (đã thay đổi kích thước) và 0 được trả về thành công. Nếu không, -1 sẽ được trả về và một ngoại lệ được đặt và *unicode sẽ không bị ảnh hưởng.

Hàm không kiểm tra nội dung chuỗi, kết quả có thể không phải là một chuỗi trong biểu diễn chuẩn.

Py_ssize_t PyUnicode_Fill(PyObject *unicode, Py_ssize_t start, Py_ssize_t length, Py_UCS4 fill_char)¶

Điền một ký tự vào chuỗi: viết fill_char vào unicode[start:start+length].

Không thành công nếu fill_char lớn hơn ký tự tối đa của chuỗi hoặc nếu chuỗi có nhiều hơn 1 tham chiếu.

Chuỗi này phải chưa được “sử dụng”. Xem PyUnicode_New() để biết chi tiết.

Trả về số lượng ký tự được viết hoặc trả về -1 và đưa ra một ngoại lệ khi có lỗi.

Added in version 3.3.

int PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)¶

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

Viết character vào chuỗi unicode tại index dựa trên số 0. Trả về 0 nếu thành công, -1 nếu có lỗi với một bộ ngoại lệ.

Hàm này kiểm tra xem unicode có phải là đối tượng Unicode hay không, chỉ mục không nằm ngoài giới hạn và số tham chiếu của đối tượng là một. Xem PyUnicode_WRITE() để biết phiên bản bỏ qua các bước kiểm tra này và bạn phải chịu trách nhiệm về chúng.

Chuỗi này phải chưa được “sử dụng”. Xem PyUnicode_New() để biết chi tiết.

Added in version 3.3.

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)¶

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

Đọc một ký tự từ một chuỗi. Hàm này kiểm tra xem unicode có phải là đối tượng Unicode và chỉ mục không nằm ngoài giới hạn, trái ngược với PyUnicode_READ_CHAR(), hàm này không thực hiện kiểm tra lỗi.

Trả về ký tự khi thành công, -1 bị lỗi với một bộ ngoại lệ.

Added in version 3.3.

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.
Trả về chuỗi con của unicode, từ chỉ mục ký tự start (được bao gồm) đến chỉ mục ký tự end (bị loại trừ). Các chỉ số tiêu cực không được hỗ trợ. Nếu có lỗi, hãy đặt ngoại lệ và trả về NULL.

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)¶: Một phần của ABI ổn định kể từ phiên bản 3.7.
Sao chép chuỗi unicode vào bộ đệm UCS4, bao gồm ký tự null, nếu copy_null được đặt. Trả về NULL và đặt một ngoại lệ khi có lỗi (cụ thể là SystemError nếu buflen nhỏ hơn độ dài của unicode). buffer được trả về thành công.

Added in version 3.3.

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶: Một phần của ABI ổn định kể từ phiên bản 3.7.
Sao chép chuỗi unicode vào bộ đệm UCS4 mới được phân bổ bằng PyMem_Malloc(). Nếu điều này không thành công, NULL sẽ được trả về cùng với bộ MemoryError. Bộ đệm được trả về luôn có thêm một điểm mã null.

Added in version 3.3.

Mã hóa miền địa phương¶

Mã hóa miền địa phương hiện tại có thể được sử dụng để giải mã văn bản từ hệ điều hành.

PyObject *PyUnicode_DecodeLocaleAndSize(const char *str, Py_ssize_t length, const char *errors)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.

Giải mã chuỗi từ UTF-8 trên Android và VxWorks hoặc từ mã hóa ngôn ngữ hiện tại trên các nền tảng khác. Trình xử lý lỗi được hỗ trợ là "strict" và "surrogateescape" (PEP 383). Bộ giải mã sử dụng trình xử lý lỗi "strict" nếu errors là NULL. str phải kết thúc bằng ký tự null nhưng không được chứa ký tự null được nhúng.

Sử dụng PyUnicode_DecodeFSDefaultAndSize() để giải mã một chuỗi từ filesystem encoding and error handler.

Hàm này bỏ qua Python UTF-8 Mode.

Xem thêm

Chức năng Py_DecodeLocale().

Added in version 3.3.

Thay đổi trong phiên bản 3.7: Hàm hiện cũng sử dụng mã hóa ngôn ngữ hiện tại cho trình xử lý lỗi surrogateescape, ngoại trừ trên Android. Trước đây, Py_DecodeLocale() được sử dụng cho surrogateescape và mã hóa ngôn ngữ hiện tại được sử dụng cho strict.

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.
Tương tự như PyUnicode_DecodeLocaleAndSize(), nhưng tính độ dài chuỗi bằng strlen().

Added in version 3.3.

PyObject *PyUnicode_EncodeLocale(PyObject *unicode, const char *errors)¶

Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định kể từ phiên bản 3.7.

Mã hóa đối tượng Unicode thành UTF-8 trên Android và VxWorks hoặc mã hóa ngôn ngữ hiện tại trên các nền tảng khác. Trình xử lý lỗi được hỗ trợ là "strict" và "surrogateescape" (PEP 383). Bộ mã hóa sử dụng trình xử lý lỗi "strict" nếu errors là NULL. Trả về một đối tượng bytes. unicode không thể chứa các ký tự null được nhúng.

Sử dụng PyUnicode_EncodeFSDefault() để mã hóa một chuỗi thành filesystem encoding and error handler.

Hàm này bỏ qua Python UTF-8 Mode.

Xem thêm

Chức năng Py_EncodeLocale().

Added in version 3.3.

Thay đổi trong phiên bản 3.7: Hàm hiện cũng sử dụng mã hóa ngôn ngữ hiện tại cho trình xử lý lỗi surrogateescape, ngoại trừ trên Android. Trước đây, Py_EncodeLocale() được sử dụng cho surrogateescape và mã hóa ngôn ngữ hiện tại được sử dụng cho strict.

Mã hóa hệ thống tập tin¶

Chức năng mã hóa và giải mã từ filesystem encoding and error handler (PEP 383 và PEP 529).

Để mã hóa tên tệp thành bytes trong quá trình phân tích cú pháp đối số, nên sử dụng trình chuyển đổi "O&", chuyển PyUnicode_FSConverter() làm hàm chuyển đổi:

int PyUnicode_FSConverter(PyObject *obj, void *result)¶

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

PyArg_Parse* converter: mã hóa các đối tượng str -- thu được trực tiếp hoặc thông qua giao diện os.PathLike -- sang bytes bằng PyUnicode_EncodeFSDefault(); Các đối tượng bytes được xuất ra nguyên trạng. result phải là địa chỉ của biến C thuộc loại PyObject* (hoặc PyBytesObject*). Nếu thành công, hãy đặt biến thành strong reference mới thành bytes object, biến này phải được giải phóng khi không còn được sử dụng và trả về giá trị khác 0 (Py_CLEANUP_SUPPORTED). Các byte rỗng được nhúng không được phép đưa vào kết quả. Nếu thất bại, hãy trả lại 0 với một bộ ngoại lệ.

Nếu obj là NULL, hàm sẽ giải phóng một tham chiếu mạnh được lưu trữ trong biến được tham chiếu bởi result và trả về 1.

Added in version 3.1.

Thay đổi trong phiên bản 3.6: Chấp nhận path-like object.

Để giải mã tên tệp thành str trong quá trình phân tích cú pháp đối số, nên sử dụng bộ chuyển đổi "O&", chuyển PyUnicode_FSDecoder() làm hàm chuyển đổi:

int PyUnicode_FSDecoder(PyObject *obj, void *result)¶

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

PyArg_Parse* converter: giải mã các đối tượng bytes -- thu được trực tiếp hoặc gián tiếp thông qua giao diện os.PathLike -- sang str bằng PyUnicode_DecodeFSDefaultAndSize(); Các đối tượng str được xuất ra nguyên trạng. result phải là địa chỉ của biến C thuộc loại PyObject* (hoặc PyUnicodeObject*). Nếu thành công, hãy đặt biến thành strong reference mới thành Unicode object, biến này phải được giải phóng khi không còn được sử dụng và trả về giá trị khác 0 (Py_CLEANUP_SUPPORTED). Các ký tự null được nhúng không được phép trong kết quả. Nếu thất bại, hãy trả lại 0 với một bộ ngoại lệ.

Nếu obj là NULL, hãy giải phóng tham chiếu mạnh tới đối tượng được tham chiếu bởi result và trả về 1.

Added in version 3.2.

Thay đổi trong phiên bản 3.6: Chấp nhận path-like object.

PyObject *PyUnicode_DecodeFSDefaultAndSize(const char *str, Py_ssize_t size)¶

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

Giải mã một chuỗi từ filesystem encoding and error handler.

Nếu bạn cần giải mã một chuỗi từ mã hóa miền địa phương hiện tại, hãy sử dụng PyUnicode_DecodeLocaleAndSize().

Xem thêm

Chức năng Py_DecodeLocale().

Thay đổi trong phiên bản 3.6: Zz000zz hiện đã được sử dụng.

PyObject *PyUnicode_DecodeFSDefault(const char *str)¶

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

Giải mã chuỗi kết thúc null từ filesystem encoding and error handler.

Nếu biết độ dài chuỗi, hãy sử dụng PyUnicode_DecodeFSDefaultAndSize().

Thay đổi trong phiên bản 3.6: Zz000zz hiện đã được sử dụng.

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)¶

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

Mã hóa một đối tượng Unicode thành filesystem encoding and error handler và trả về bytes. Lưu ý rằng đối tượng bytes thu được có thể chứa byte rỗng.

Nếu bạn cần mã hóa một chuỗi thành mã hóa miền địa phương hiện tại, hãy sử dụng PyUnicode_EncodeLocale().

Xem thêm

Chức năng Py_EncodeLocale().

Added in version 3.2.

Thay đổi trong phiên bản 3.6: Zz000zz hiện đã được sử dụng.

Hỗ trợ wchar_t¶

wchar_t hỗ trợ cho các nền tảng hỗ trợ nó:

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode từ bộ đệm wchar_t wstr của size đã cho. Truyền -1 làm size chỉ ra rằng hàm phải tự tính toán độ dài bằng cách sử dụng wcslen(). Trả về NULL khi thất bại.

Py_ssize_t PyUnicode_AsWideChar(PyObject *unicode, wchar_t *wstr, Py_ssize_t size)¶

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

Sao chép nội dung đối tượng Unicode vào bộ đệm wchar_t wstr. Tối đa size wchar_t ký tự được sao chép (không bao gồm ký tự kết thúc null có thể ở cuối). Trả về số ký tự wchar_t đã sao chép hoặc -1 trong trường hợp có lỗi.

Khi wstr là NULL, thay vào đó hãy trả về size cần thiết để lưu trữ tất cả unicode bao gồm cả giá trị rỗng kết thúc.

Lưu ý rằng chuỗi wchar_t* kết quả có thể bị kết thúc bằng null hoặc không. Người gọi có trách nhiệm đảm bảo rằng chuỗi wchar_t* được kết thúc bằng null trong trường hợp ứng dụng yêu cầu điều này. Ngoài ra, hãy lưu ý rằng chuỗi wchar_t* có thể chứa các ký tự null, điều này sẽ khiến chuỗi bị cắt bớt khi sử dụng với hầu hết các hàm C.

wchar_t *PyUnicode_AsWideCharString(PyObject *unicode, Py_ssize_t *size)¶

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

Chuyển đổi đối tượng Unicode thành chuỗi ký tự rộng. Chuỗi đầu ra luôn kết thúc bằng ký tự null. Nếu size không phải là NULL, hãy ghi số ký tự rộng (không bao gồm ký tự kết thúc null ở cuối) vào *size. Note that the resulting zz000zz string might contain null characters, which would cause the string to be truncated when used with most C functions. If size là NULL và chuỗi wchar_t* chứa các ký tự null mà ValueError được nâng lên.

Trả về bộ đệm được phân bổ bởi PyMem_New (sử dụng PyMem_Free() để giải phóng nó) nếu thành công. Nếu có lỗi, trả về NULL và *size không được xác định. Tăng MemoryError nếu cấp phát bộ nhớ không thành công.

Added in version 3.2.

Thay đổi trong phiên bản 3.7: Tăng ValueError nếu size là NULL và chuỗi wchar_t* chứa các ký tự null.

Codec tích hợp¶

Python cung cấp một bộ codec tích hợp được viết bằng C để tăng tốc độ. Tất cả các codec này đều có thể sử dụng trực tiếp thông qua các chức năng sau.

Nhiều API sau đây có hai đối số mã hóa và lỗi, đồng thời chúng có cùng ngữ nghĩa với ngữ nghĩa của hàm tạo đối tượng chuỗi str() tích hợp sẵn.

Việc đặt mã hóa thành NULL sẽ khiến mã hóa mặc định được sử dụng là UTF-8. Cuộc gọi hệ thống tệp nên sử dụng PyUnicode_FSConverter() để mã hóa tên tệp. Điều này sử dụng filesystem encoding and error handler nội bộ.

Xử lý lỗi được đặt theo lỗi cũng có thể được đặt thành NULL nghĩa là sử dụng cách xử lý mặc định được xác định cho codec. Xử lý lỗi mặc định cho tất cả các codec tích hợp là "nghiêm ngặt" (ValueError được nâng lên).

Các codec đều sử dụng một giao diện tương tự. Chỉ những sai lệch so với những điểm chung sau đây mới được ghi lại để đơn giản.

Codec chung¶

Macro sau được cung cấp:

Py_UNICODE_REPLACEMENT_CHARACTER¶

Điểm mã Unicode U+FFFD (ký tự thay thế).

Ký tự Unicode này được sử dụng làm ký tự thay thế trong quá trình giải mã nếu đối số errors được đặt thành "thay thế".

Đây là các API codec chung:

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã byte size của chuỗi được mã hóa str. encoding và errors có ý nghĩa tương tự như các tham số cùng tên trong hàm tích hợp str(). Codec được sử dụng sẽ được tra cứu bằng cách sử dụng sổ đăng ký codec Python. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Mã hóa một đối tượng Unicode và trả về kết quả dưới dạng đối tượng byte Python. encoding và errors có ý nghĩa tương tự như các tham số cùng tên trong phương thức Unicode encode(). Codec được sử dụng sẽ được tra cứu bằng cách sử dụng sổ đăng ký codec Python. Trả về NULL nếu codec đưa ra ngoại lệ.

Codec UTF-8¶

Đây là các API codec UTF-8:

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa UTF-8 str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nếu consumed là NULL, hãy cư xử như PyUnicode_DecodeUTF8(). Nếu consumed không phải là NULL, các chuỗi byte UTF-8 không hoàn chỉnh ở cuối sẽ không được coi là lỗi. Những byte đó sẽ không được giải mã và số byte đã được giải mã sẽ được lưu trữ trong consumed.

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)¶

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

Mã hóa một đối tượng Unicode bằng UTF-8 và trả về kết quả dưới dạng đối tượng byte Python. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Hàm không thành công nếu chuỗi chứa các điểm mã thay thế (U+D800 - U+DFFF).

const char *PyUnicode_AsUTF8AndSize(PyObject *unicode, Py_ssize_t *size)¶

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

Trả về con trỏ tới mã hóa UTF-8 của đối tượng Unicode và lưu trữ kích thước của biểu diễn được mã hóa (tính bằng byte) trong size. Đối số size có thể là NULL; trong trường hợp này sẽ không có kích thước nào được lưu trữ. Bộ đệm được trả về luôn có thêm một byte rỗng được thêm vào (không có trong size), bất kể có bất kỳ điểm mã null nào khác hay không.

Nếu có lỗi, hãy đặt một ngoại lệ, đặt size thành -1 (nếu không phải là NULL) và trả về NULL.

Hàm không thành công nếu chuỗi chứa các điểm mã thay thế (U+D800 - U+DFFF).

Điều này lưu trữ biểu diễn UTF-8 của chuỗi trong đối tượng Unicode và các cuộc gọi tiếp theo sẽ trả về một con trỏ tới cùng một bộ đệm. Người gọi không chịu trách nhiệm giải phóng bộ đệm. Bộ đệm được giải phóng và các con trỏ tới nó trở nên không hợp lệ khi đối tượng Unicode bị thu gom rác.

Added in version 3.3.

Thay đổi trong phiên bản 3.7: Kiểu trả về bây giờ là const char * thay vì char *.

Thay đổi trong phiên bản 3.10: Chức năng này là một phần của limited API.

const char *PyUnicode_AsUTF8(PyObject *unicode)¶: Là PyUnicode_AsUTF8AndSize() nhưng không lưu trữ kích thước.

Cảnh báo

Hàm này không có bất kỳ hành vi đặc biệt nào đối với null characters được nhúng trong unicode. Kết quả là, các chuỗi chứa ký tự null sẽ vẫn còn trong chuỗi được trả về, mà một số hàm C có thể hiểu là phần cuối của chuỗi, dẫn đến bị cắt bớt. Nếu vấn đề bị cắt bớt thì bạn nên sử dụng PyUnicode_AsUTF8AndSize() để thay thế.

Added in version 3.3.

Thay đổi trong phiên bản 3.7: Kiểu trả về bây giờ là const char * thay vì char *.

Codec UTF-32¶

Đây là các API codec UTF-32:

PyObject *PyUnicode_DecodeUTF32(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

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

Giải mã byte size từ chuỗi đệm được mã hóa UTF-32 và trả về đối tượng Unicode tương ứng. errors (nếu không phải NULL) xác định cách xử lý lỗi. Nó mặc định là "nghiêm ngặt".

Nếu byteorder không phải là NULL, bộ giải mã sẽ bắt đầu giải mã theo thứ tự byte đã cho:

*byteorder == -1: endian nhỏ
*byteorder == 0: thứ tự gốc
*byteorder == 1: endian lớn

Nếu *byteorder bằng 0 và bốn byte đầu tiên của dữ liệu đầu vào là dấu thứ tự byte (BOM), bộ giải mã sẽ chuyển sang thứ tự byte này và BOM không được sao chép vào chuỗi Unicode kết quả. Nếu *byteorder là -1 hoặc 1, mọi dấu thứ tự byte đều được sao chép vào đầu ra.

Sau khi hoàn thành, *byteorder được đặt thành thứ tự byte hiện tại ở cuối dữ liệu đầu vào.

Nếu byteorder là NULL, codec sẽ bắt đầu ở chế độ thứ tự gốc.

Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nếu consumed là NULL, hãy cư xử như PyUnicode_DecodeUTF32(). Nếu consumed không phải là NULL, PyUnicode_DecodeUTF32Stateful() sẽ không coi các chuỗi UTF-32 byte không hoàn chỉnh ở cuối (chẳng hạn như số byte không chia hết cho 4) là lỗi. Những byte đó sẽ không được giải mã và số byte đã được giải mã sẽ được lưu trữ trong consumed.

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về chuỗi byte Python bằng cách sử dụng mã hóa UTF-32 theo thứ tự byte gốc. Chuỗi luôn bắt đầu bằng dấu BOM. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec UTF-16¶

Đây là các API codec UTF-16:

PyObject *PyUnicode_DecodeUTF16(const char *str, Py_ssize_t size, const char *errors, int *byteorder)¶

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

Giải mã byte size từ chuỗi đệm được mã hóa UTF-16 và trả về đối tượng Unicode tương ứng. errors (nếu không phải NULL) xác định cách xử lý lỗi. Nó mặc định là "nghiêm ngặt".

Nếu byteorder không phải là NULL, bộ giải mã sẽ bắt đầu giải mã theo thứ tự byte đã cho:

*byteorder == -1: endian nhỏ
*byteorder == 0: thứ tự gốc
*byteorder == 1: endian lớn

Nếu *byteorder bằng 0 và hai byte đầu tiên của dữ liệu đầu vào là dấu thứ tự byte (BOM), bộ giải mã sẽ chuyển sang thứ tự byte này và BOM không được sao chép vào chuỗi Unicode kết quả. Nếu *byteorder là -1 hoặc 1, thì bất kỳ dấu thứ tự byte nào cũng được sao chép vào đầu ra (trong đó nó sẽ tạo ra ký tự \ufeff hoặc \ufffe).

Sau khi hoàn thành, *byteorder được đặt theo thứ tự byte hiện tại ở cuối dữ liệu đầu vào.

Nếu byteorder là NULL, codec sẽ bắt đầu ở chế độ thứ tự gốc.

Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nếu consumed là NULL, hãy cư xử như PyUnicode_DecodeUTF16(). Nếu consumed không phải là NULL, thì PyUnicode_DecodeUTF16Stateful() sẽ không coi các chuỗi UTF-16 byte không hoàn chỉnh ở cuối (chẳng hạn như số byte lẻ hoặc cặp thay thế bị phân tách) là lỗi. Những byte đó sẽ không được giải mã và số byte đã được giải mã sẽ được lưu trữ trong consumed.

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Trả về chuỗi byte Python bằng cách sử dụng mã hóa UTF-16 theo thứ tự byte gốc. Chuỗi luôn bắt đầu bằng dấu BOM. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec UTF-7¶

Đây là các API codec UTF-7:

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa UTF-7 str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nếu consumed là NULL, hãy cư xử như PyUnicode_DecodeUTF7(). Nếu consumed không phải là NULL, các phần UTF-7 base-64 không hoàn chỉnh sẽ không bị coi là lỗi. Những byte đó sẽ không được giải mã và số byte đã được giải mã sẽ được lưu trữ trong consumed.

Bộ giải mã Unicode-Escape¶

Đây là các API codec "Unicode Escape":

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi mã hóa Unicode-Escape str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Mã hóa đối tượng Unicode bằng Unicode-Escape và trả về kết quả dưới dạng đối tượng byte. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec Raw-Unicode-Escape¶

Đây là các API codec "Raw Unicode Escape":

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa Raw-Unicode-Escape str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Mã hóa một đối tượng Unicode bằng Raw-Unicode-Escape và trả về kết quả dưới dạng đối tượng byte. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec Latin-1¶

Đây là các API codec Latin-1: Latin-1 tương ứng với 256 thứ tự Unicode đầu tiên và chỉ những thứ tự này mới được codec chấp nhận trong quá trình mã hóa.

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa Latin-1 str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Mã hóa một đối tượng Unicode bằng Latin-1 và trả về kết quả dưới dạng đối tượng byte Python. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec ASCII¶

Đây là các API codec ASCII. Chỉ chấp nhận dữ liệu ASCII 7 bit. Tất cả các mã khác đều tạo ra lỗi.

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa ASCII str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Mã hóa một đối tượng Unicode bằng ASCII và trả về kết quả dưới dạng đối tượng byte Python. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Codec bản đồ ký tự¶

Codec này đặc biệt ở chỗ nó có thể được sử dụng để triển khai nhiều codec khác nhau (và thực tế đây là điều đã được thực hiện để có được hầu hết các codec tiêu chuẩn có trong gói encodings). Codec sử dụng ánh xạ để mã hóa và giải mã các ký tự. Các đối tượng ánh xạ được cung cấp phải hỗ trợ giao diện ánh xạ __getitem__(); từ điển và trình tự hoạt động tốt.

Đây là các API codec ánh xạ:

PyObject *PyUnicode_DecodeCharmap(const char *str, Py_ssize_t length, PyObject *mapping, const char *errors)¶

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

Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa str bằng cách sử dụng đối tượng mapping đã cho. Trả về NULL nếu codec đưa ra ngoại lệ.

Nếu mapping là NULL, giải mã Latin-1 sẽ được áp dụng. Ngược lại, mapping phải ánh xạ các thứ tự byte (số nguyên trong phạm vi từ 0 đến 255) thành chuỗi Unicode, số nguyên (sau đó được hiểu là thứ tự Unicode) hoặc None. Các byte dữ liệu chưa được ánh xạ -- những byte gây ra LookupError, cũng như những byte được ánh xạ tới None, 0xFFFE hoặc '\ufffe', đều được coi là ánh xạ không xác định và gây ra lỗi.

PyObject *PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping)¶

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

Mã hóa một đối tượng Unicode bằng cách sử dụng đối tượng mapping đã cho và trả về kết quả dưới dạng đối tượng byte. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

Đối tượng mapping phải ánh xạ các số nguyên thứ tự Unicode thành các đối tượng byte, các số nguyên trong phạm vi từ 0 đến 255 hoặc None. Thứ tự ký tự chưa được ánh xạ (những thứ gây ra LookupError) cũng như được ánh xạ tới None được coi là "ánh xạ không xác định" và gây ra lỗi.

Codec API sau đây đặc biệt trong việc ánh xạ Unicode sang Unicode.

PyObject *PyUnicode_Translate(PyObject *unicode, PyObject *table, const char *errors)¶

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

Dịch một chuỗi bằng cách áp dụng bảng ánh xạ ký tự cho chuỗi đó và trả về đối tượng Unicode thu được. Trả về NULL nếu codec đưa ra ngoại lệ.

Bảng ánh xạ phải ánh xạ các số nguyên thứ tự Unicode thành các số nguyên thứ tự Unicode hoặc None (gây ra việc xóa ký tự).

Các bảng ánh xạ chỉ cần cung cấp giao diện __getitem__(); từ điển và trình tự hoạt động tốt. Thứ tự ký tự chưa được ánh xạ (những thứ gây ra LookupError) sẽ được giữ nguyên và được sao chép nguyên trạng.

errors có ý nghĩa thông thường đối với codec. Nó có thể là NULL cho biết sử dụng cách xử lý lỗi mặc định.

codec MBCS cho Windows¶

Đây là các API codec MBCS. Chúng hiện chỉ có sẵn trên Windows và sử dụng bộ chuyển đổi Win32 MBCS để thực hiện chuyển đổi. Lưu ý rằng MBCS (hoặc DBCS) là một loại mã hóa, không chỉ một. Mã hóa mục tiêu được xác định bởi cài đặt người dùng trên máy chạy codec.

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định on Windows kể từ phiên bản 3.7.
Tạo một đối tượng Unicode bằng cách giải mã các byte size của chuỗi được mã hóa MBCS str. Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định on Windows kể từ phiên bản 3.7.
Nếu consumed là NULL, hãy cư xử như PyUnicode_DecodeMBCS(). Nếu consumed không phải là NULL thì PyUnicode_DecodeMBCSStateful() sẽ không giải mã byte dẫn đầu và số byte đã được giải mã sẽ được lưu trong consumed.

PyObject *PyUnicode_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định on Windows kể từ phiên bản 3.7.
Tương tự như PyUnicode_DecodeMBCSStateful(), ngoại trừ việc sử dụng trang mã do code_page chỉ định.

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định on Windows kể từ phiên bản 3.7.
Mã hóa một đối tượng Unicode bằng MBCS và trả về kết quả dưới dạng đối tượng byte Python. Xử lý lỗi là "nghiêm ngặt". Trả về NULL nếu codec đưa ra ngoại lệ.

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định on Windows kể từ phiên bản 3.7.
Mã hóa đối tượng Unicode bằng cách sử dụng trang mã được chỉ định và trả về đối tượng byte Python. Trả về NULL nếu codec đưa ra ngoại lệ. Sử dụng trang mã CP_ACP để lấy bộ mã hóa MBCS.

Added in version 3.3.

Phương thức và hàm Slot¶

Các API sau có khả năng xử lý các đối tượng và chuỗi Unicode ở đầu vào (chúng tôi gọi chúng là chuỗi trong phần mô tả) và trả về các đối tượng hoặc số nguyên Unicode nếu thích hợp.

Tất cả đều trả về NULL hoặc -1 nếu xảy ra ngoại lệ.

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nối hai chuỗi tạo thành một chuỗi Unicode mới.

PyObject *PyUnicode_Split(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

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

Tách một chuỗi đưa ra danh sách các chuỗi Unicode. Nếu sep là NULL, việc phân tách sẽ được thực hiện ở tất cả các chuỗi con khoảng trắng. Nếu không, sự phân chia sẽ xảy ra tại dấu phân cách đã cho. Nhiều nhất việc chia tách maxsplit sẽ được thực hiện. Nếu âm, không có giới hạn nào được đặt. Dấu phân cách không được bao gồm trong danh sách kết quả.

Nếu có lỗi, hãy trả về NULL với một bộ ngoại lệ.

Tương đương với str.split().

PyObject *PyUnicode_RSplit(PyObject *unicode, PyObject *sep, Py_ssize_t maxsplit)¶

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

Tương tự như PyUnicode_Split(), nhưng việc phân tách sẽ được thực hiện bắt đầu từ cuối chuỗi.

Nếu có lỗi, hãy trả về NULL với một bộ ngoại lệ.

Tương đương với str.rsplit().

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Tách chuỗi Unicode khi ngắt dòng, trả về danh sách các chuỗi Unicode. CRLF được coi là ngắt một dòng. Nếu keepends là 0, các ký tự ngắt dòng sẽ không được đưa vào chuỗi kết quả.

PyObject *PyUnicode_Partition(PyObject *unicode, PyObject *sep)¶

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

Tách một chuỗi Unicode ở lần xuất hiện đầu tiên của sep và trả về một bộ 3 chứa phần trước dấu phân cách, chính dấu phân cách và phần sau dấu phân cách. Nếu không tìm thấy dấu phân cách, hãy trả về bộ 3 chứa chính chuỗi đó, theo sau là hai chuỗi trống.

sep không được để trống.

Nếu có lỗi, hãy trả về NULL với một bộ ngoại lệ.

Tương đương với str.partition().

PyObject *PyUnicode_RPartition(PyObject *unicode, PyObject *sep)¶

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

Tương tự như PyUnicode_Partition(), nhưng phân tách chuỗi Unicode ở lần xuất hiện cuối cùng của sep. Nếu không tìm thấy dấu phân cách, hãy trả về bộ 3 chứa hai chuỗi trống, theo sau là chính chuỗi đó.

sep không được để trống.

Nếu có lỗi, hãy trả về NULL với một bộ ngoại lệ.

Tương đương với str.rpartition().

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Nối một chuỗi các chuỗi bằng cách sử dụng separator đã cho và trả về chuỗi Unicode kết quả.

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: Một phần của ABI ổn định.
Trả về 1 nếu substr khớp với unicode[start:end] ở đầu đuôi đã cho (direction == -1 có nghĩa là thực hiện khớp tiền tố, direction == 1 khớp hậu tố), nếu không thì 0. Trả về -1 nếu xảy ra lỗi.

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: Một phần của ABI ổn định.
Trả về vị trí đầu tiên của substr trong unicode[start:end] bằng cách sử dụng direction đã cho (direction == 1 có nghĩa là thực hiện tìm kiếm tiến lên, direction == -1 là tìm kiếm lùi). Giá trị trả về là chỉ số của kết quả khớp đầu tiên; giá trị -1 cho biết không tìm thấy kết quả khớp nào và -2 cho biết đã xảy ra lỗi và một ngoại lệ đã được đặt.

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)¶: Một phần của ABI ổn định kể từ phiên bản 3.7.
Trả về vị trí đầu tiên của ký tự ch trong unicode[start:end] bằng cách sử dụng direction đã cho (direction == 1 có nghĩa là thực hiện tìm kiếm tiến lên, direction == -1 là tìm kiếm lùi). Giá trị trả về là chỉ số của kết quả khớp đầu tiên; giá trị -1 cho biết không tìm thấy kết quả khớp nào và -2 cho biết đã xảy ra lỗi và một ngoại lệ đã được đặt.

Added in version 3.3.

Thay đổi trong phiên bản 3.7: start và end hiện được điều chỉnh để hoạt động giống unicode[start:end].

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)¶: Một phần của ABI ổn định.
Trả về số lần xuất hiện không chồng chéo của substr trong unicode[start:end]. Trả về -1 nếu xảy ra lỗi.

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)¶: Giá trị trả về: Tham chiếu mới. Một phần của ABI ổn định.
Thay thế tối đa các lần xuất hiện maxcount của substr trong unicode bằng replstr và trả về đối tượng Unicode kết quả. maxcount == -1 có nghĩa là thay thế tất cả các lần xuất hiện.

int PyUnicode_Compare(PyObject *left, PyObject *right)¶

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

So sánh hai chuỗi và trả về -1, 0, 1 tương ứng nhỏ hơn, bằng và lớn hơn.

Hàm này trả về -1 khi bị lỗi, vì vậy ta nên gọi PyErr_Occurred() để kiểm tra lỗi.

Xem thêm

Chức năng PyUnicode_Equal().

int PyUnicode_Equal(PyObject *a, PyObject *b)¶

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

Kiểm tra xem hai chuỗi có bằng nhau không:

Trả về 1 nếu a bằng b.
Trả về 0 nếu a không bằng b.
Đặt ngoại lệ TypeError và trả về -1 nếu a hoặc b không phải là đối tượng str.

Hàm luôn thành công nếu a và b là đối tượng str.

Hàm này hoạt động với các lớp con str nhưng không hỗ trợ phương thức __eq__() tùy chỉnh.

Xem thêm

Chức năng PyUnicode_Compare().

Added in version 3.14.

int PyUnicode_EqualToUTF8AndSize(PyObject *unicode, const char *string, Py_ssize_t size)¶

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

So sánh một đối tượng Unicode với bộ đệm char được hiểu là được mã hóa UTF-8 hoặc ASCII và trả về true (1) nếu chúng bằng nhau hoặc trả về false (0) nếu ngược lại. Nếu đối tượng Unicode chứa các điểm mã thay thế (U+D800 - U+DFFF) hoặc chuỗi C không hợp lệ UTF-8, thì trả về sai (0).

Chức năng này không đưa ra ngoại lệ.

Added in version 3.13.

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)¶: Một phần của ABI ổn định kể từ phiên bản 3.13.
Tương tự như PyUnicode_EqualToUTF8AndSize(), nhưng tính toán độ dài string bằng strlen(). Nếu đối tượng Unicode chứa ký tự null, kết quả trả về là sai (0).

Added in version 3.13.

int PyUnicode_CompareWithASCIIString(PyObject *unicode, const char *string)¶

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

So sánh một đối tượng Unicode, unicode, với string và trả về -1, 0, 1 tương ứng nhỏ hơn, bằng và lớn hơn. Tốt nhất là chỉ truyền các chuỗi được mã hóa ASCII, nhưng hàm sẽ diễn giải chuỗi đầu vào là ISO-8859-1 nếu nó chứa các ký tự không phải ASCII.

Chức năng này không đưa ra ngoại lệ.

PyObject *PyUnicode_RichCompare(PyObject *left, PyObject *right, int op)¶

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

Rich so sánh hai chuỗi Unicode và trả về một trong các chuỗi sau:

NULL trong trường hợp ngoại lệ được nêu ra
Py_True hoặc Py_False để so sánh thành công
Py_NotImplemented trong trường hợp không xác định được tổ hợp loại

Các giá trị có thể có của op là Py_GT, Py_GE, Py_EQ, Py_NE, Py_LT và Py_LE.

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)¶: 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 chuỗi mới từ format và args; điều này tương tự với format % args.

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)¶

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

Kiểm tra xem substr có nằm trong unicode hay không và trả về true hoặc false tương ứng.

substr phải ép buộc thành chuỗi Unicode một phần tử. -1 được trả về nếu có lỗi.

void PyUnicode_InternInPlace(PyObject **p_unicode)¶

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

Thực hiện đối số *p_unicode tại chỗ. Đối số phải là địa chỉ của biến con trỏ trỏ tới đối tượng chuỗi Unicode Python. Nếu có một chuỗi nội bộ hiện có giống với *p_unicode, thì nó sẽ đặt *p_unicode cho chuỗi đó (giải phóng tham chiếu đến đối tượng chuỗi cũ và tạo một strong reference mới cho đối tượng chuỗi nội bộ), nếu không, nó sẽ để nguyên *p_unicode và thực hiện nó.

(Làm rõ: mặc dù có rất nhiều cuộc thảo luận về tài liệu tham khảo, hãy coi chức năng này là trung lập về tham chiếu. Bạn phải sở hữu đối tượng bạn truyền vào; sau lệnh gọi, bạn không còn sở hữu tham chiếu được truyền vào nữa, nhưng bạn mới sở hữu kết quả.)

Hàm này không bao giờ đưa ra một ngoại lệ. Nếu có lỗi, nó sẽ giữ nguyên đối số của mình mà không thực hiện nó.

Các phiên bản của lớp con của str có thể không được thực hiện, nghĩa là PyUnicode_CheckExact(*p_unicode) phải đúng. Nếu không, thì -- như với bất kỳ lỗi nào khác -- đối số sẽ không thay đổi.

Lưu ý rằng các chuỗi nội bộ không phải là "bất tử". Bạn phải tham khảo kết quả để được hưởng lợi từ việc thực tập.

PyObject *PyUnicode_InternFromString(const char *str)¶

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

Sự kết hợp của PyUnicode_FromString() và PyUnicode_InternInPlace(), dành cho các chuỗi được phân bổ tĩnh.

Trả về một tham chiếu mới ("được sở hữu") cho một đối tượng chuỗi Unicode mới đã được thực hiện nội bộ hoặc một đối tượng chuỗi được thực hiện trước đó có cùng giá trị.

Python có thể giữ một tham chiếu đến kết quả hoặc đặt nó thành immortal, ngăn không cho nó bị thu gom rác kịp thời. Để thực hiện số lượng chuỗi khác nhau không giới hạn, chẳng hạn như các chuỗi đến từ đầu vào của người dùng, hãy gọi trực tiếp PyUnicode_FromString() và PyUnicode_InternInPlace().

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶: Trả về giá trị khác 0 nếu str được thực hiện, 0 nếu không. Đối số str phải là một chuỗi; điều này không được kiểm tra. Chức năng này luôn thành công.

Giá trị trả về khác 0 có thể mang thông tin bổ sung về how chuỗi được thực hiện. Ý nghĩa của các giá trị khác 0 như vậy, cũng như các chi tiết liên quan đến nội bộ của từng chuỗi cụ thể, có thể thay đổi giữa các phiên bản CPython.

PyUnicodeNhà văn¶

PyUnicodeWriter API có thể được sử dụng để tạo đối tượng str Python.

Added in version 3.14.

type PyUnicodeWriter¶

Một ví dụ về trình soạn thảo Unicode.

Phiên bản phải bị hủy bởi PyUnicodeWriter_Finish() nếu thành công hoặc PyUnicodeWriter_Discard() do lỗi.

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶

Tạo một phiên bản trình soạn thảo Unicode.

length phải lớn hơn hoặc bằng 0.

Nếu length lớn hơn 0, hãy phân bổ trước bộ đệm bên trong gồm các ký tự length.

Đặt một ngoại lệ và trả về NULL khi có lỗi.

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶

Trả về đối tượng str Python cuối cùng và hủy phiên bản trình ghi.

Đặt một ngoại lệ và trả về NULL khi có lỗi.

Phiên bản người viết không hợp lệ sau lệnh gọi này.

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶

Loại bỏ bộ đệm Unicode bên trong và hủy phiên bản trình ghi.

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 viết không hợp lệ sau lệnh gọi này.

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶

Viết ký tự Unicode đơn ch vào writer.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_WriteUTF8(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

Giải mã chuỗi str từ UTF-8 ở chế độ nghiêm ngặt và ghi đầu ra vào writer.

size là độ dài chuỗi tính bằng byte. Nếu size bằng -1, hãy gọi strlen(str) để lấy độ dài chuỗi.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

Xem thêm PyUnicodeWriter_DecodeUTF8Stateful().

int PyUnicodeWriter_WriteASCII(PyUnicodeWriter *writer, const char *str, Py_ssize_t size)¶

Viết chuỗi ASCII str vào writer.

size là độ dài chuỗi tính bằng byte. Nếu size bằng -1, hãy gọi strlen(str) để lấy độ dài chuỗi.

str chỉ được chứa các ký tự ASCII. Hành vi này không được xác định nếu str chứa các ký tự không phải ASCII.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_WriteWideChar(PyUnicodeWriter *writer, const wchar_t *str, Py_ssize_t size)¶

Viết chuỗi rộng str vào writer.

size là một số ký tự rộng. Nếu size bằng -1, hãy gọi wcslen(str) để lấy độ dài chuỗi.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_WriteUCS4(PyUnicodeWriter *writer, Py_UCS4 *str, Py_ssize_t size)¶

Viết chuỗi UCS4 str vào writer.

size là một số ký tự UCS4.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_WriteStr(PyUnicodeWriter *writer, PyObject *obj)¶

Gọi PyObject_Str() trên obj và ghi kết quả đầu ra vào writer.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

Để viết một lớp con str ghi đè phương thức __str__(), PyUnicode_FromObject() có thể được sử dụng để lấy chuỗi gốc.

int PyUnicodeWriter_WriteRepr(PyUnicodeWriter *writer, PyObject *obj)¶

Gọi PyObject_Repr() trên obj và ghi kết quả đầu ra vào writer.

Nếu obj là NULL thì viết chuỗi "<NULL>" vào writer.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

Thay đổi trong phiên bản 3.14.4: Đã thêm hỗ trợ cho NULL.

int PyUnicodeWriter_WriteSubstring(PyUnicodeWriter *writer, PyObject *str, Py_ssize_t start, Py_ssize_t end)¶

Viết chuỗi con str[start:end] vào writer.

str phải là đối tượng str của Python. start phải lớn hơn hoặc bằng 0 và nhỏ hơn hoặc bằng end. end phải nhỏ hơn hoặc bằng độ dài str.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_Format(PyUnicodeWriter *writer, const char *format, ...)¶

Tương tự như PyUnicode_FromFormat(), nhưng ghi kết quả trực tiếp vào writer.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

int PyUnicodeWriter_DecodeUTF8Stateful(PyUnicodeWriter *writer, const char *string, Py_ssize_t length, const char *errors, Py_ssize_t *consumed)¶

Giải mã chuỗi str từ UTF-8 bằng trình xử lý lỗi errors và ghi đầu ra vào writer.

size là độ dài chuỗi tính bằng byte. Nếu size bằng -1, hãy gọi strlen(str) để lấy độ dài chuỗi.

errors là tên error handler, chẳng hạn như "replace". Nếu errors là NULL, hãy sử dụng trình xử lý lỗi nghiêm ngặt.

Nếu consumed không phải là NULL, hãy đặt *consumed thành số byte được giải mã thành công. Nếu consumed là NULL, hãy coi các chuỗi byte UTF-8 không hoàn chỉnh ở cuối là một lỗi.

Nếu thành công, hãy trả về 0. Nếu có lỗi, hãy đặt một ngoại lệ, giữ nguyên trình ghi và trả về -1.

Xem thêm PyUnicodeWriter_WriteUTF8().

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

API sau đây không được dùng nữa.

type Py_UNICODE¶: Đây là typedef của wchar_t, là loại 16 bit hoặc loại 32 bit tùy thuộc vào nền tảng. Vui lòng sử dụng wchar_t trực tiếp để thay thế.

Thay đổi trong phiên bản 3.3: Trong các phiên bản trước, đây là loại 16 bit hay loại 32 bit tùy thuộc vào việc bạn chọn phiên bản Unicode "hẹp" hay "rộng" của Python tại thời điểm xây dựng.

Không được dùng nữa kể từ phiên bản 3.13, sẽ bị xóa trong phiên bản 3.15.

int PyUnicode_READY(PyObject *unicode)¶: Không làm gì cả và trả lại 0. Zz001zz này chỉ được giữ lại để tương thích ngược nhưng không có kế hoạch loại bỏ nó.

Added in version 3.3.

Sắp loại bỏ từ phiên bản 3.10: Zz001zz này không làm gì kể từ Python 3.12. Trước đây, điều này cần được gọi cho mỗi chuỗi được tạo bằng API cũ (PyUnicode_FromUnicode() hoặc tương tự).

unsigned int PyUnicode_IS_READY(PyObject *unicode)¶: Không làm gì cả và trả lại 1. Zz001zz này chỉ được giữ lại để tương thích ngược nhưng không có kế hoạch loại bỏ nó.

Added in version 3.3.

Sắp loại bỏ từ phiên bản 3.14: Zz001zz này không làm gì kể từ Python 3.12. Trước đây, điều này có thể được gọi để kiểm tra xem PyUnicode_READY() có cần thiết hay không.

Đối tượng và Codec Unicode¶

Đối tượng Unicode¶

Loại Unicode¶

Thuộc tính ký tự Unicode¶

Tạo và truy cập chuỗi Unicode¶

Mã hóa miền địa phương¶

Mã hóa hệ thống tập tin¶

Hỗ trợ wchar_t¶

Codec tích hợp¶

Codec chung¶

Codec UTF-8¶

Codec UTF-32¶

Codec UTF-16¶

Codec UTF-7¶

Bộ giải mã Unicode-Escape¶

Codec Raw-Unicode-Escape¶

Codec Latin-1¶

Codec ASCII¶

Codec bản đồ ký tự¶

codec MBCS cho Windows¶

Phương thức và hàm Slot¶

PyUnicodeNhà văn¶

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

Table of Contents

Chủ đề trước

Chủ đề tiếp

Trang này