Unicode 物件和編解碼器

Unicode 物件

自從 Python 3.3 中實現了 PEP 393 以來，Unicode 物件內部使用多種表示形式，以便在保持記憶體效率的同時處理完整的 Unicode 字元範圍。 對於所有程式碼點都低於 128、256 或 65536 的字串，存在特殊情況； 否則，程式碼點必須低於 1114112（這是完整的 Unicode 範圍）。

UTF-8 表示形式是按需建立並快取在 Unicode 物件中的。

注意

自從 Python 3.12 以來，Py_UNICODE 表示形式已被刪除，同時棄用了相關 API。 有關更多資訊，請參閱 PEP 623。

Unicode 型別

這些是用於 Python 中 Unicode 實現的基本 Unicode 物件型別

type Py_UCS4

type Py_UCS2

type Py_UCS1

屬於 穩定 ABI 的一部分。

這些型別是 typedef，分別用於足夠寬以包含 32 位、16 位和 8 位字元的無符號整數型別。 在處理單個 Unicode 字元時，請使用 Py_UCS4。

在 3.3 版本中新增。

type Py_UNICODE

這是 wchar_t 的 typedef，它是一個 16 位型別或 32 位型別，具體取決於平臺。

在 3.3 版本中更改：在以前的版本中，這是一種 16 位型別或 32 位型別，具體取決於你在構建時選擇的是 Python 的“窄” Unicode 版本還是“寬” Unicode 版本。

自 3.13 版本起已棄用，將在 3.15 版本中刪除。

type PyASCIIObject

type PyCompactUnicodeObject

type PyUnicodeObject

這些 PyObject 的子型別表示 Python Unicode 物件。 在幾乎所有情況下，它們都不應直接使用，因為所有處理 Unicode 物件的 API 函式都接受並返回 PyObject 指標。

在 3.3 版本中新增。

PyTypeObject PyUnicode_Type

屬於 穩定 ABI 的一部分。

這個 PyTypeObject 的例項表示 Python Unicode 型別。 它以 str 的形式暴露給 Python 程式碼。

以下 API 是 C 宏和靜態行內函數，用於快速檢查和訪問 Unicode 物件的內部只讀資料

int PyUnicode_Check(PyObject *obj)

如果物件 obj 是 Unicode 物件或 Unicode 子型別的例項，則返回 true。 此函式始終成功。

int PyUnicode_CheckExact(PyObject *obj)

如果物件 obj 是 Unicode 物件，但不是子型別的例項，則返回 true。 此函式始終成功。

int PyUnicode_READY(PyObject *unicode)

返回 0。 此 API 僅為向後相容性而保留。

在 3.3 版本中新增。

自 3.10 版本起已棄用：此 API 自 Python 3.12 起不再執行任何操作。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)

返回 Unicode 字串的長度，以程式碼點為單位。 unicode 必須是“規範”表示形式（未檢查）的 Unicode 物件。

在 3.3 版本中新增。

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)

Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)

Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)

返回指向規範表示形式的指標，該指標轉換為 UCS1、UCS2 或 UCS4 整數型別，以便直接訪問字元。 如果規範表示形式具有正確的字元大小，則不執行檢查； 請使用 PyUnicode_KIND() 來選擇正確的函式。

在 3.3 版本中新增。

PyUnicode_1BYTE_KIND

PyUnicode_2BYTE_KIND

PyUnicode_4BYTE_KIND

返回 PyUnicode_KIND() 宏的值。

在 3.3 版本中新增。

在 3.12 版本中更改：PyUnicode_WCHAR_KIND 已刪除。

int PyUnicode_KIND(PyObject *unicode)

返回一個 PyUnicode kind 常量（見上文），該常量指示此 Unicode 物件每個字元使用多少位元組來儲存其資料。unicode 必須是“規範”表示形式的 Unicode 物件（未檢查）。

在 3.3 版本中新增。

void *PyUnicode_DATA(PyObject *unicode)

返回指向原始 Unicode 緩衝區的 void 指標。unicode 必須是“規範”表示形式的 Unicode 物件（未檢查）。

在 3.3 版本中新增。

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

寫入規範表示形式的 data（透過 PyUnicode_DATA() 獲取）。此函式不執行任何健全性檢查，旨在在迴圈中使用。呼叫者應快取從其他呼叫獲得的 kind 值和 data 指標。index 是字串中的索引（從 0 開始），value 是應寫入該位置的新程式碼點值。

在 3.3 版本中新增。

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)

從規範表示形式的 data（透過 PyUnicode_DATA() 獲取）讀取程式碼點。不執行任何檢查或準備呼叫。

在 3.3 版本中新增。

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)

從 Unicode 物件 unicode 讀取字元，該物件必須採用“規範”表示形式。 如果您執行多個連續讀取，則此方法不如 PyUnicode_READ() 效率高。

在 3.3 版本中新增。

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)

返回適合基於 unicode 建立另一個字串的最大程式碼點，該字串必須採用“規範”表示形式。 這始終是一個近似值，但比迭代字串效率更高。

在 3.3 版本中新增。

int PyUnicode_IsIdentifier(PyObject *unicode)

屬於 穩定 ABI 的一部分。

如果該字串根據語言定義（請參閱識別符號和關鍵字部分）是有效的識別符號，則返回 1。否則返回 0。

在 3.9 版本中更改：如果字串未準備就緒，該函式不再呼叫 Py_FatalError()。

Unicode 字元屬性

Unicode 提供了許多不同的字元屬性。最常用的屬性可以透過這些宏獲得，這些宏根據 Python 配置對映到 C 函式。

int Py_UNICODE_ISSPACE(Py_UCS4 ch)

根據 ch 是否為空白字元，返回 1 或 0。

int Py_UNICODE_ISLOWER(Py_UCS4 ch)

根據 ch 是否為小寫字元，返回 1 或 0。

int Py_UNICODE_ISUPPER(Py_UCS4 ch)

根據 ch 是否為大寫字元，返回 1 或 0。

int Py_UNICODE_ISTITLE(Py_UCS4 ch)

根據 ch 是否為首字母大寫的字元，返回 1 或 0。

int Py_UNICODE_ISLINEBREAK(Py_UCS4 ch)

根據 ch 是否為換行符，返回 1 或 0。

int Py_UNICODE_ISDECIMAL(Py_UCS4 ch)

根據 ch 是否為十進位制字元，返回 1 或 0。

int Py_UNICODE_ISDIGIT(Py_UCS4 ch)

根據 ch 是否為數字字元，返回 1 或 0。

int Py_UNICODE_ISNUMERIC(Py_UCS4 ch)

根據 ch 是否為數字字元，返回 1 或 0。

int Py_UNICODE_ISALPHA(Py_UCS4 ch)

根據 ch 是否為字母字元，返回 1 或 0。

int Py_UNICODE_ISALNUM(Py_UCS4 ch)

根據 ch 是否為字母數字字元，返回 1 或 0。

int Py_UNICODE_ISPRINTABLE(Py_UCS4 ch)

根據ch是否為可列印字元，返回 1 或 0。不可列印字元是指在 Unicode 字元資料庫中定義為“其他”或“分隔符”的字元，但 ASCII 空格 (0x20) 除外，該空格被認為是可列印的。（請注意，此處的“可列印字元”是指當對字串呼叫 repr() 時不應被轉義的字元。它與寫入 sys.stdout 或 sys.stderr 的字串的處理方式無關。）

這些 API 可用於快速直接的字元轉換

Py_UCS4 Py_UNICODE_TOLOWER(Py_UCS4 ch)

返回轉換為小寫字母的字元 ch。

Py_UCS4 Py_UNICODE_TOUPPER(Py_UCS4 ch)

返回轉換為大寫字母的字元 ch。

Py_UCS4 Py_UNICODE_TOTITLE(Py_UCS4 ch)

返回轉換為首字母大寫形式的字元 ch。

int Py_UNICODE_TODECIMAL(Py_UCS4 ch)

返回轉換為十進位制正整數的字元 ch。如果無法轉換，則返回 -1。此函式不會引發異常。

int Py_UNICODE_TODIGIT(Py_UCS4 ch)

返回轉換為單個數字整數的字元 ch。如果無法轉換，則返回 -1。此函式不會引發異常。

double Py_UNICODE_TONUMERIC(Py_UCS4 ch)

返回轉換為 double 型別的字元 ch。如果無法轉換，則返回 -1.0。此函式不會引發異常。

這些 API 可用於處理代理項

int Py_UNICODE_IS_SURROGATE(Py_UCS4 ch)

檢查 ch 是否為代理項（0xD800 <= ch <= 0xDFFF）。

int Py_UNICODE_IS_HIGH_SURROGATE(Py_UCS4 ch)

檢查 ch 是否為高位代理項（0xD800 <= ch <= 0xDBFF）。

int Py_UNICODE_IS_LOW_SURROGATE(Py_UCS4 ch)

檢查 ch 是否為低位代理項（0xDC00 <= ch <= 0xDFFF）。

Py_UCS4 Py_UNICODE_JOIN_SURROGATES(Py_UCS4 high, Py_UCS4 low)

連線兩個代理程式碼點，並返回一個單獨的 Py_UCS4 值。high 和 low 分別是代理對中的前導和尾隨代理項。high 必須在 [0xD800; 0xDBFF] 範圍內，low 必須在 [0xDC00; 0xDFFF] 範圍內。

建立和訪問 Unicode 字串

要建立 Unicode 物件並訪問它們的基本序列屬性，請使用這些 API

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

返回值：新引用。

建立一個新的 Unicode 物件。maxchar 應該是要放置在字串中的真正的最大程式碼點。作為近似值，它可以四捨五入到序列 127、255、65535、1114111 中最接近的值。

這是分配新 Unicode 物件的推薦方法。使用此函式建立的物件不可調整大小。

發生錯誤時，設定異常並返回 NULL。

在 3.3 版本中新增。

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

返回值：新引用。

使用給定的 kind（可能的值為 PyUnicode_1BYTE_KIND 等，如 PyUnicode_KIND() 返回的）建立一個新的 Unicode 物件。buffer 必須指向一個數組，該陣列的每個字元包含 1、2 或 4 個位元組的 size 個單元，如 kind 所指定。

如有必要，輸入 buffer 將被複制並轉換為規範表示形式。例如，如果 buffer 是一個 UCS4 字串（PyUnicode_4BYTE_KIND），並且它僅由 UCS1 範圍內的程式碼點組成，則它將被轉換為 UCS1（PyUnicode_1BYTE_KIND）。

在 3.3 版本中新增。

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

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

從字元緩衝區 str 建立一個 Unicode 物件。這些位元組將被解釋為 UTF-8 編碼。緩衝區被複制到新物件中。返回值可能是一個共享物件，即不允許修改資料。

當出現以下情況時，此函式會引發 SystemError

• size < 0,

• str 為 NULL 且 size > 0

在 3.12 版本中更改: 不再允許 str == NULL 且 size > 0。

PyObject *PyUnicode_FromString(const char *str)

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

從以空字元結尾的 UTF-8 編碼字元緩衝區 str 建立一個 Unicode 物件。

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

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

接受一個 C 語言的 printf() 風格的 format 字串和可變數量的引數，計算生成的 Python Unicode 字串的大小，並返回一個格式化了值的字串。可變引數必須是 C 型別，並且必須與 format ASCII 編碼字串中的格式字元完全對應。

轉換說明符包含兩個或多個字元，並具有以下組成部分，這些組成部分必須按此順序出現：

1. 標記說明符開始的 '%' 字元。

2. 轉換標誌（可選），會影響某些轉換型別的結果。

3. 最小欄位寬度（可選）。如果指定為 '*' （星號），則實際寬度在下一個引數中給出，該引數必須是 int 型別，並且要轉換的物件在最小欄位寬度和可選精度之後。

4. 精度（可選），以 '.' （點）後跟精度給出。如果指定為 '*' （星號），則實際精度在下一個引數中給出，該引數必須是 int 型別，並且要轉換的值在精度之後。

5. 長度修飾符（可選）。

6. 轉換型別。

轉換標誌字元是：

標誌	含義
0	對於數值，轉換將進行零填充。
-	轉換後的值將左對齊（如果同時給出 0 標誌，則覆蓋該標誌）。

以下整數轉換（d、i、o、u、x 或 X）的長度修飾符指定引數的型別（預設為 int）：

修飾符	型別
l	long 或 unsigned long
ll	long long 或 unsigned long long
j	intmax_t 或 uintmax_t
z	size_t 或 ssize_t
t	ptrdiff_t

以下轉換 s 或 V 的長度修飾符 l 指定引數的型別為 const wchar_t*。

轉換說明符為：

轉換說明符	型別	註釋
%	n/a	字面值 % 字元。
d，i	由長度修飾符指定	有符號 C 整數的十進位制表示形式。
u	由長度修飾符指定	無符號 C 整數的十進位制表示形式。
o	由長度修飾符指定	無符號 C 整數的八進位制表示形式。
x	由長度修飾符指定	無符號 C 整數的十六進位制表示形式（小寫）。
X	由長度修飾符指定	無符號 C 整數的十六進位制表示形式（大寫）。
c	int	單個字元。
s	const char* 或 const wchar_t*	以 null 結尾的 C 字元陣列。
p	const void*	C 指標的十六進位制表示形式。與 printf("%p") 大致等效，但保證以字面值 0x 開頭，而不管平臺的 printf 產生什麼。
A	PyObject*	呼叫 ascii() 的結果。
U	PyObject*	一個 Unicode 物件。
V	PyObject*, const char* 或 const wchar_t*	一個 Unicode 物件（可以為 NULL），以及一個以 null 結尾的 C 字元陣列作為第二個引數（如果第一個引數為 NULL，則將使用該引數）。
S	PyObject*	呼叫 PyObject_Str() 的結果。
R	PyObject*	呼叫 PyObject_Repr() 的結果。
T	PyObject*	獲取物件型別的完全限定名稱；呼叫 PyType_GetFullyQualifiedName()。
#T	PyObject*	類似於 T 格式，但使用冒號（:）作為模組名稱和限定名稱之間的分隔符。
N	PyTypeObject*	獲取型別的完全限定名稱；呼叫 PyType_GetFullyQualifiedName()。
#N	PyTypeObject*	類似於 N 格式，但使用冒號（:）作為模組名稱和限定名稱之間的分隔符。

注意

寬度格式化單位是字元數，而不是位元組數。精度格式化單位是 "%s" 和 "%V" 的位元組數或 wchar_t 項數（如果使用長度修飾符 l），並且對於 "%A"、"%U"、"%S"、"%R" 和 "%V" （如果 PyObject* 引數不為 NULL），則為字元數。

注意

與 C printf() 不同，即使為整數轉換（d、i、u、o、x 或 X）給出了精度，0 標誌仍然有效。

在 3.2 版本中更改: 添加了對 "%lld" 和 "%llu" 的支援。

在 3.3 版本中更改: 添加了對 "%li"、"%lli" 和 "%zi" 的支援。

在 3.4 版本中更改: 添加了對 "%s"、"%A"、"%U"、"%V"、"%S"、"%R" 的寬度和精度格式化器的支援。

3.12 版本更改: 支援轉換說明符 o 和 X。支援長度修飾符 j 和 t。長度修飾符現在應用於所有整數轉換。長度修飾符 l 現在應用於轉換說明符 s 和 V。支援可變寬度和精度 *。支援標誌 -。

無法識別的格式字元現在會設定一個 SystemError。在之前的版本中，它會導致格式字串的其餘部分原樣複製到結果字串，並丟棄任何多餘的引數。

3.13 版本更改: 添加了對 %T, %#T, %N 和 %#N 格式的支援。

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

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

與 PyUnicode_FromFormat() 相同，只是它只接受兩個引數。

PyObject *PyUnicode_FromObject(PyObject *obj)

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

如有必要，將 Unicode 子型別的例項複製到新的真 Unicode 物件。如果 obj 已經是真 Unicode 物件（不是子型別），則返回對該物件的新 強引用。

Unicode 或其子型別之外的物件將導致 TypeError。

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

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

將編碼的物件 obj 解碼為 Unicode 物件。

bytes, bytearray 和其他 位元組類物件 根據給定的 encoding 進行解碼，並使用 errors 定義的錯誤處理。兩者都可以為 NULL 以使介面使用預設值（有關詳細資訊，請參閱 內建編解碼器）。

所有其他物件，包括 Unicode 物件，都會導致設定 TypeError。

如果發生錯誤，API 返回 NULL。呼叫者負責減少返回物件的引用計數。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode)

自 3.7 版本以來，它是 穩定 ABI 的一部分。

返回 Unicode 物件的長度，以程式碼點表示。

如果發生錯誤，設定異常並返回 -1。

在 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)

將字元從一個 Unicode 物件複製到另一個 Unicode 物件。此函式在必要時執行字元轉換，並在可能的情況下回退到 memcpy()。如果發生錯誤，則返回 -1 並設定異常，否則返回複製的字元數。

在 3.3 版本中新增。

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

用一個字元填充字串：將 fill_char 寫入 unicode[start:start+length]。

如果 fill_char 大於字串的最大字元，或者字串的引用計數大於 1，則會失敗。

返回寫入的字元數，如果發生錯誤，則返回 -1 並引發異常。

在 3.3 版本中新增。

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

自 3.7 版本以來，它是 穩定 ABI 的一部分。

將字元寫入字串。該字串必須是透過 PyUnicode_New() 建立的。由於 Unicode 字串應該是不可變的，因此該字串不能被共享，或者尚未被雜湊。

此函式檢查 unicode 是否為 Unicode 物件，索引是否未超出範圍，以及物件是否可以安全修改（即其引用計數為 1）。

成功時返回 0，如果發生錯誤則返回 -1 並設定異常。

在 3.3 版本中新增。

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)

自 3.7 版本以來，它是 穩定 ABI 的一部分。

從字串讀取字元。此函式檢查 unicode 是否為 Unicode 物件，並且索引是否未超出範圍，這與 PyUnicode_READ_CHAR() 不同，後者不執行錯誤檢查。

成功時返回字元，如果發生錯誤則返回 -1 並設定異常。

在 3.3 版本中新增。

PyObject *PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)

返回值：新的引用。 自 3.7 版本起成為 穩定 ABI 的一部分。

返回 unicode 的一個子字串，從字元索引 start (包括) 到字元索引 end (不包括)。不支援負索引。如果發生錯誤，則設定一個異常並返回 NULL。

在 3.3 版本中新增。

Py_UCS4 *PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)

自 3.7 版本以來，它是 穩定 ABI 的一部分。

將字串 unicode 複製到 UCS4 緩衝區中，如果設定了 copy_null，則包含一個空字元。如果發生錯誤（特別是，如果 buflen 小於 unicode 的長度，則會引發 SystemError），則返回 NULL 並設定一個異常。成功時返回 buffer。

在 3.3 版本中新增。

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)

自 3.7 版本以來，它是 穩定 ABI 的一部分。

將字串 unicode 複製到使用 PyMem_Malloc() 分配的新 UCS4 緩衝區中。如果此操作失敗，則返回 NULL 並設定一個 MemoryError。返回的緩衝區始終附加一個額外的空程式碼點。

在 3.3 版本中新增。

區域設定編碼

當前區域設定編碼可用於解碼來自作業系統的文字。

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

返回值：新的引用。 自 3.7 版本起成為 穩定 ABI 的一部分。

在 Android 和 VxWorks 上從 UTF-8 解碼字串，或者在其他平臺上從當前區域設定編碼解碼字串。支援的錯誤處理程式是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 為 NULL，則解碼器使用 "strict" 錯誤處理程式。str 必須以空字元結尾，但不能包含嵌入的空字元。

使用 PyUnicode_DecodeFSDefaultAndSize() 從 檔案系統編碼和錯誤處理程式解碼字串。

此函式忽略 Python UTF-8 模式。

參見

Py_DecodeLocale() 函式。

在 3.3 版本中新增。

在 3.7 版本中更改: 該函式現在還對 surrogateescape 錯誤處理程式使用當前區域設定編碼，Android 除外。以前，Py_DecodeLocale() 用於 surrogateescape，而當前區域設定編碼用於 strict。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors)

返回值：新的引用。 自 3.7 版本起成為 穩定 ABI 的一部分。

與 PyUnicode_DecodeLocaleAndSize() 類似，但使用 strlen() 計算字串長度。

在 3.3 版本中新增。

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

返回值：新的引用。 自 3.7 版本起成為 穩定 ABI 的一部分。

在 Android 和 VxWorks 上將 Unicode 物件編碼為 UTF-8，或者在其他平臺上編碼為當前區域設定編碼。支援的錯誤處理程式是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 為 NULL，則編碼器使用 "strict" 錯誤處理程式。返回 bytes 物件。unicode 不能包含嵌入的空字元。

使用 PyUnicode_EncodeFSDefault() 將字串編碼為 檔案系統編碼和錯誤處理程式。

此函式忽略 Python UTF-8 模式。

參見

Py_EncodeLocale() 函式。

在 3.3 版本中新增。

在 3.7 版本中更改: 該函式現在還對 surrogateescape 錯誤處理程式使用當前區域設定編碼，Android 除外。以前，Py_EncodeLocale() 用於 surrogateescape，而當前區域設定編碼用於 strict。

檔案系統編碼

用於編碼到和解碼自檔案系統編碼和錯誤處理程式的函式 (PEP 383 和 PEP 529)。

要在引數解析期間將檔名編碼為 bytes，應使用 "O&" 轉換器，並將 PyUnicode_FSConverter() 作為轉換函式傳遞。

int PyUnicode_FSConverter(PyObject *obj, void *result)

屬於 穩定 ABI 的一部分。

ParseTuple 轉換器：將 str 物件（直接獲取或透過 os.PathLike 介面獲取）使用 PyUnicode_EncodeFSDefault() 編碼為 bytes；bytes 物件按原樣輸出。result 必須是一個 PyBytesObject*，當不再使用時必須釋放它。

在版本 3.1 中加入。

在 3.6 版本中變更: 接受 路徑類物件。

要在引數解析期間將檔名解碼為 str，應使用 "O&" 轉換器，並將 PyUnicode_FSDecoder() 作為轉換函式傳遞。

int PyUnicode_FSDecoder(PyObject *obj, void *result)

屬於 穩定 ABI 的一部分。

ParseTuple 轉換器：將 bytes 物件（直接獲取或透過 os.PathLike 介面間接獲取）使用 PyUnicode_DecodeFSDefaultAndSize() 解碼為 str；str 物件按原樣輸出。result 必須是一個 PyUnicodeObject*，當不再使用時必須釋放它。

在版本 3.2 中加入。

在 3.6 版本中變更: 接受 路徑類物件。

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

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

從 檔案系統編碼和錯誤處理程式 解碼字串。

如果需要從當前區域設定編碼解碼字串，請使用 PyUnicode_DecodeLocaleAndSize()。

參見

Py_DecodeLocale() 函式。

在 3.6 版本中變更: 現在使用 檔案系統錯誤處理程式。

PyObject *PyUnicode_DecodeFSDefault(const char *str)

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

從 檔案系統編碼和錯誤處理程式 解碼以 null 結尾的字串。

如果字串長度已知，請使用 PyUnicode_DecodeFSDefaultAndSize()。

在 3.6 版本中變更: 現在使用 檔案系統錯誤處理程式。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

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

將 Unicode 物件編碼為 檔案系統編碼和錯誤處理程式，並返回 bytes。請注意，生成的 bytes 物件可以包含 null 位元組。

如果需要將字串編碼為當前區域設定編碼，請使用 PyUnicode_EncodeLocale()。

參見

Py_EncodeLocale() 函式。

在版本 3.2 中加入。

在 3.6 版本中變更: 現在使用 檔案系統錯誤處理程式。

wchar_t 支援

為支援 wchar_t 的平臺提供 wchar_t 支援

PyObject *PyUnicode_FromWideChar(const wchar_t *wstr, Py_ssize_t size)

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

從給定 size 的 wchar_t 緩衝區 wstr 建立一個 Unicode 物件。將 -1 作為 size 傳遞表示函式必須使用 wcslen() 自行計算長度。失敗時返回 NULL。

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

屬於 穩定 ABI 的一部分。

將 Unicode 物件的內容複製到 wchar_t 緩衝區 wstr 中。最多複製 size 個 wchar_t 字元（不包括可能出現的尾部 null 終止字元）。返回複製的 wchar_t 字元數，如果發生錯誤則返回 -1。

當 wstr 為 NULL 時，改為返回儲存所有 unicode（包括終止 null）所需的 size。

請注意，生成的 wchar_t* 字串可能以 null 結尾，也可能不以 null 結尾。呼叫者有責任確保 wchar_t* 字串在應用程式需要時以 null 結尾。另請注意，wchar_t* 字串可能包含 null 字元，這會導致字串在使用大多數 C 函式時被截斷。

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

自 3.7 版本以來，它是 穩定 ABI 的一部分。

將 Unicode 物件轉換為寬字元字串。輸出字串始終以 null 字元結尾。如果 size 不是 NULL，則將寬字元數（不包括尾部的 null 終止字元）寫入 *size。請注意，生成的 wchar_t 字串可能包含 null 字元，這會導致字串在使用大多數 C 函式時被截斷。如果 size 是 NULL 並且 wchar_t* 字串包含 null 字元，則會引發 ValueError 異常。

成功時返回 PyMem_New 分配的緩衝區（使用 PyMem_Free() 來釋放它）。如果出錯，則返回 NULL 並且 *size 是未定義的。如果記憶體分配失敗，則引發 MemoryError 異常。

在版本 3.2 中加入。

在 3.7 版本中變更: 如果 size 為 NULL 並且 wchar_t* 字串包含 null 字元，則引發 ValueError 異常。

內建編解碼器

Python 提供了一組用 C 編寫以提高速度的內建編解碼器。所有這些編解碼器都可以透過以下函式直接使用。

以下許多 API 接受兩個引數 encoding 和 errors，它們的語義與內建的 str() 字串物件建構函式的引數語義相同。

將 encoding 設定為 NULL 會導致使用預設編碼，即 UTF-8。檔案系統呼叫應使用 PyUnicode_FSConverter() 來編碼檔名。這在內部使用檔案系統編碼和錯誤處理程式。

錯誤處理由 errors 設定，errors 也可以設定為 NULL，表示使用為編解碼器定義的預設處理方式。所有內建編解碼器的預設錯誤處理方式都是“strict”（會引發 ValueError 異常）。

所有編解碼器都使用類似的介面。為了簡單起見，只記錄與以下通用介面的偏差。

通用編解碼器

以下是通用編解碼器 API

PyObject *PyUnicode_Decode(const char *str, Py_ssize_t size, const char *encoding, const char *errors)

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

透過解碼編碼字串 str 的 size 位元組來建立一個 Unicode 物件。encoding 和 errors 的含義與內建函式 str() 中同名的引數相同。要使用的編解碼器將透過 Python 編解碼器登錄檔查詢。如果編解碼器引發了異常，則返回 NULL。

PyObject *PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors)

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

對 Unicode 物件進行編碼，並將結果作為 Python 位元組物件返回。encoding 和 errors 的含義與 Unicode encode() 方法中同名的引數相同。要使用的編解碼器將透過 Python 編解碼器登錄檔查詢。如果編解碼器引發了異常，則返回 NULL。

UTF-8 編解碼器

以下是 UTF-8 編解碼器 API

PyObject *PyUnicode_DecodeUTF8(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 UTF-8 編碼的字串 str 的 size 位元組來建立一個 Unicode 物件。如果編解碼器引發了異常，則返回 NULL。

PyObject *PyUnicode_DecodeUTF8Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

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

如果 consumed 為 NULL，則其行為類似於 PyUnicode_DecodeUTF8()。如果 consumed 不為 NULL，則尾隨的不完整 UTF-8 位元組序列不會被視為錯誤。這些位元組不會被解碼，並且已解碼的位元組數將儲存在 consumed 中。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

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

使用 UTF-8 對 Unicode 物件進行編碼，並將結果作為 Python 位元組物件返回。錯誤處理為“strict”。如果編解碼器引發了異常，則返回 NULL。

如果字串包含代理碼位（U+D800 - U+DFFF），則該函式將失敗。

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

自 3.10 版本起，屬於 穩定 ABI 的一部分。

返回指向 Unicode 物件的 UTF-8 編碼的指標，並將編碼表示的大小（以位元組為單位）儲存在 size 中。size 引數可以為 NULL；在這種情況下，不會儲存大小。無論是否有任何其他空程式碼點，返回的緩衝區始終附加一個額外的空位元組（不包括在 size 中）。

如果發生錯誤，則設定異常，將 size 設定為 -1（如果它不為 NULL），並返回 NULL。

如果字串包含代理碼位（U+D800 - U+DFFF），則該函式將失敗。

這會將字串的 UTF-8 表示形式快取在 Unicode 物件中，後續呼叫將返回指向同一緩衝區的指標。呼叫者不負責釋放緩衝區。當 Unicode 物件被垃圾回收時，緩衝區將被釋放，並且指向該緩衝區的指標將失效。

在 3.3 版本中新增。

在 3.7 版本中更改: 返回型別現在是 const char * 而不是 char *。

在 3.10 版本中更改: 此函式是 有限 API 的一部分。

const char *PyUnicode_AsUTF8(PyObject *unicode)

與 PyUnicode_AsUTF8AndSize() 相同，但不儲存大小。

在 3.3 版本中新增。

在 3.7 版本中更改: 返回型別現在是 const char * 而不是 char *。

UTF-32 編解碼器

以下是 UTF-32 編解碼器 API

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

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

從一個 UTF-32 編碼的緩衝區字串解碼 size 位元組，並返回對應的 Unicode 物件。errors （如果非 NULL）定義了錯誤處理方式。它預設為 “strict”。

如果 byteorder 非 NULL，解碼器將使用給定的位元組順序開始解碼。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

如果 *byteorder 為零，且輸入資料的前四個位元組是位元組順序標記 (BOM)，解碼器將切換到此位元組順序，並且 BOM 不會被複制到結果 Unicode 字串中。如果 *byteorder 是 -1 或 1，任何位元組順序標記都會被複制到輸出中。

完成後，*byteorder 將被設定為輸入資料末尾的當前位元組順序。

如果 byteorder 為 NULL，則編解碼器以本地位元組順序模式啟動。

如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_DecodeUTF32Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

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

如果 consumed 為 NULL，則行為類似於 PyUnicode_DecodeUTF32()。如果 consumed 不為 NULL，PyUnicode_DecodeUTF32Stateful() 不會將末尾不完整的 UTF-32 位元組序列（例如，位元組數不能被 4 整除的位元組序列）視為錯誤。這些位元組將不會被解碼，並且已解碼的位元組數將儲存在 consumed 中。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)

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

返回一個使用本地位元組順序的 UTF-32 編碼的 Python 位元組字串。該字串始終以 BOM 標記開頭。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

UTF-16 編解碼器

這些是 UTF-16 編解碼器的 API

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

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

從一個 UTF-16 編碼的緩衝區字串解碼 size 位元組，並返回對應的 Unicode 物件。errors （如果非 NULL）定義了錯誤處理方式。它預設為 “strict”。

如果 byteorder 非 NULL，解碼器將使用給定的位元組順序開始解碼。

*byteorder == -1: little endian
*byteorder == 0:  native order
*byteorder == 1:  big endian

如果 *byteorder 為零，且輸入資料的前兩個位元組是位元組順序標記 (BOM)，解碼器將切換到此位元組順序，並且 BOM 不會被複制到結果 Unicode 字串中。如果 *byteorder 是 -1 或 1，任何位元組順序標記都會被複制到輸出（它將導致 \ufeff 或 \ufffe 字元）。

完成後，*byteorder 將被設定為輸入資料末尾的當前位元組順序。

如果 byteorder 為 NULL，則編解碼器以本地位元組順序模式啟動。

如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_DecodeUTF16Stateful(const char *str, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

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

如果 consumed 為 NULL，則行為類似於 PyUnicode_DecodeUTF16()。如果 consumed 不為 NULL，PyUnicode_DecodeUTF16Stateful() 不會將末尾不完整的 UTF-16 位元組序列（例如，位元組數為奇數或拆分的代理對）視為錯誤。這些位元組將不會被解碼，並且已解碼的位元組數將儲存在 consumed 中。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

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

返回一個使用本地位元組順序的 UTF-16 編碼的 Python 位元組字串。該字串始終以 BOM 標記開頭。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

UTF-7 編解碼器

這些是 UTF-7 編解碼器的 API

PyObject *PyUnicode_DecodeUTF7(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 UTF-7 編碼的字串 str 的 size 位元組來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_DecodeUTF7Stateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

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

如果 consumed 為 NULL，則行為與 PyUnicode_DecodeUTF7() 相同。如果 consumed 不為 NULL，則尾部不完整的 UTF-7 base-64 部分不會被視為錯誤。這些位元組將不會被解碼，並且已解碼的位元組數將儲存在 consumed 中。

Unicode-Escape 編解碼器

這些是 “Unicode Escape” 編解碼器 API

PyObject *PyUnicode_DecodeUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 size 位元組的 Unicode-Escape 編碼的字串 str 來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

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

使用 Unicode-Escape 編碼 Unicode 物件，並將結果作為位元組物件返回。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

Raw-Unicode-Escape 編解碼器

這些是 “Raw Unicode Escape” 編解碼器 API

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 size 位元組的 Raw-Unicode-Escape 編碼的字串 str 來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

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

使用 Raw-Unicode-Escape 編碼 Unicode 物件，並將結果作為位元組物件返回。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

Latin-1 編解碼器

這些是 Latin-1 編解碼器 API：Latin-1 對應於前 256 個 Unicode 序數，並且在編碼期間僅接受這些序數。

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 size 位元組的 Latin-1 編碼的字串 str 來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

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

使用 Latin-1 編碼 Unicode 物件，並將結果作為 Python 位元組物件返回。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

ASCII 編解碼器

這些是 ASCII 編解碼器 API。僅接受 7 位 ASCII 資料。所有其他程式碼都會生成錯誤。

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)

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

透過解碼 size 位元組的 ASCII 編碼的字串 str 來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

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

使用 ASCII 編碼 Unicode 物件，並將結果作為 Python 位元組物件返回。錯誤處理為 “strict”。如果編解碼器引發異常，則返回 NULL。

字元對映編解碼器

此編解碼器的特殊之處在於，它可用於實現許多不同的編解碼器（實際上，這是為了獲得 encodings 包中包含的大多數標準編解碼器而完成的）。該編解碼器使用對映來編碼和解碼字元。提供的對映物件必須支援 __getitem__() 對映介面；字典和序列效果良好。

這些是對映編解碼器 API

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

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

使用給定的 mapping 物件解碼 size 位元組的編碼字串 str，建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

如果 mapping 為 NULL，則將應用 Latin-1 解碼。否則，mapping 必須將位元組序數（0 到 255 範圍內的整數）對映到 Unicode 字串、整數（然後將其解釋為 Unicode 序數）或 None。未對映的資料位元組（導致 LookupError 的位元組，以及對映到 None、0xFFFE 或 '\ufffe' 的位元組）被視為未定義的對映並導致錯誤。

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

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

使用給定的mapping物件編碼 Unicode 物件，並將結果作為位元組物件返回。錯誤處理是“嚴格的”。如果編解碼器引發異常，則返回 NULL。

mapping 物件必須將 Unicode 序號整數對映到位元組物件、0 到 255 範圍內的整數或 None。未對映的字元序號（導致 LookupError）以及對映到 None 的序號被視為“未定義的對映”並導致錯誤。

以下編解碼器 API 的特殊之處在於它將 Unicode 對映到 Unicode。

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

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

透過將字元對映表應用於字串來翻譯字串，並返回生成的 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

對映表必須將 Unicode 序號整數對映到 Unicode 序號整數或 None（導致刪除字元）。

對映表只需要提供 __getitem__() 介面；字典和序列可以很好地工作。未對映的字元序號（導致 LookupError）將保持不變，並按原樣複製。

errors 具有編解碼器的常用含義。它可以是 NULL，表示使用預設的錯誤處理。

用於 Windows 的 MBCS 編解碼器

這些是 MBCS 編解碼器 API。它們目前僅在 Windows 上可用，並使用 Win32 MBCS 轉換器來實現轉換。請注意，MBCS（或 DBCS）是一類編碼，而不僅僅是一種。目標編碼由執行編解碼器的機器上的使用者設定定義。

PyObject *PyUnicode_DecodeMBCS(const char *str, Py_ssize_t size, const char *errors)

返回值：新引用。自 3.7 版本以來，Windows 上的 穩定 ABI 的一部分。

透過解碼 MBCS 編碼字串 str 的 size 個位元組來建立 Unicode 物件。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_DecodeMBCSStateful(const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)

返回值：新引用。自 3.7 版本以來，Windows 上的 穩定 ABI 的一部分。

如果 consumed 是 NULL，則行為類似於 PyUnicode_DecodeMBCS()。如果 consumed 不是 NULL，則 PyUnicode_DecodeMBCSStateful() 將不會解碼尾隨前導位元組，並且已解碼的位元組數將儲存在 consumed 中。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

返回值：新引用。自 3.7 版本以來，Windows 上的 穩定 ABI 的一部分。

使用 MBCS 編碼 Unicode 物件，並將結果作為 Python 位元組物件返回。錯誤處理是“嚴格的”。如果編解碼器引發異常，則返回 NULL。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors)

返回值：新引用。自 3.7 版本以來，Windows 上的 穩定 ABI 的一部分。

使用指定的內碼表編碼 Unicode 物件，並返回 Python 位元組物件。如果編解碼器引發異常，則返回 NULL。使用 CP_ACP 內碼表來獲取 MBCS 編碼器。

在 3.3 版本中新增。

方法 & 插槽

方法和插槽函式

以下 API 能夠處理輸入上的 Unicode 物件和字串（我們在描述中將其稱為字串），並根據需要返回 Unicode 物件或整數。

如果發生異常，它們都返回 NULL 或 -1。

PyObject *PyUnicode_Concat(PyObject *left, PyObject *right)

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

連線兩個字串，生成新的 Unicode 字串。

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

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

分割字串，生成 Unicode 字串列表。如果 sep 是 NULL，則將在所有空白子字串處進行分割。否則，將在給定的分隔符處進行分割。最多將完成 maxsplit 次分割。如果為負數，則不設定限制。分隔符不包含在結果列表中。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)

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

在換行符處分割 Unicode 字串，返回 Unicode 字串列表。CRLF 被視為一個換行符。如果 keepends 是 0，則換行符不包含在結果字串中。

PyObject *PyUnicode_Join(PyObject *separator, PyObject *seq)

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

使用給定的separator連線字串序列，並返回生成的 Unicode 字串。

Py_ssize_t PyUnicode_Tailmatch(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

屬於 穩定 ABI 的一部分。

如果substr在給定的尾端匹配 unicode[start:end]，則返回 1 (direction == -1 表示進行字首匹配，direction == 1 表示進行字尾匹配)，否則返回 0。 如果發生錯誤，則返回 -1。

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)

屬於 穩定 ABI 的一部分。

使用給定的direction返回substr在unicode[start:end]中的第一個位置(direction == 1 表示進行正向搜尋，direction == -1 表示進行反向搜尋)。返回值是第一個匹配項的索引；值 -1 表示未找到匹配項，而 -2 表示發生錯誤且已設定異常。

Py_ssize_t PyUnicode_FindChar(PyObject *unicode, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction)

自 3.7 版本以來，它是 穩定 ABI 的一部分。

使用給定的direction返回字元ch在 unicode[start:end] 中的第一個位置(direction == 1 表示進行正向搜尋，direction == -1 表示進行反向搜尋)。返回值是第一個匹配項的索引；值 -1 表示未找到匹配項，而 -2 表示發生錯誤且已設定異常。

在 3.3 版本中新增。

在 3.7 版本中更改: start 和 end 現在被調整為像 unicode[start:end] 一樣工作。

Py_ssize_t PyUnicode_Count(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end)

屬於 穩定 ABI 的一部分。

返回 substr 在 unicode[start:end] 中不重疊出現的次數。如果發生錯誤，則返回 -1。

PyObject *PyUnicode_Replace(PyObject *unicode, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount)

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

將unicode中最多 maxcount 次出現的 substr 替換為 replstr，並返回生成的 Unicode 物件。 maxcount == -1 表示替換所有出現。

int PyUnicode_Compare(PyObject *left, PyObject *right)

屬於 穩定 ABI 的一部分。

比較兩個字串，並分別返回小於、等於和大於的 -1、0、1。

此函式在失敗時返回 -1，因此應該呼叫 PyErr_Occurred() 來檢查錯誤。

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

自 3.13 版本起，屬於穩定 ABI的一部分。

將 Unicode 物件與解釋為 UTF-8 或 ASCII 編碼的字元緩衝區進行比較，如果它們相等，則返回 true (1)，否則返回 false (0)。如果 Unicode 物件包含代理程式碼點 (U+D800 - U+DFFF) 或 C 字串不是有效的 UTF-8，則返回 false (0)。

此函式不會引發異常。

在 3.13 版本中新增。

int PyUnicode_EqualToUTF8(PyObject *unicode, const char *string)

自 3.13 版本起，屬於穩定 ABI的一部分。

類似於 PyUnicode_EqualToUTF8AndSize()，但使用 strlen() 計算 string 的長度。如果 Unicode 物件包含空字元，則返回 false (0)。

在 3.13 版本中新增。

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

屬於 穩定 ABI 的一部分。

將 Unicode 物件 unicode 與 string 進行比較，並分別返回小於、等於和大於的 -1、0 和 1。最好只傳遞 ASCII 編碼的字串，但如果輸入字串包含非 ASCII 字元，該函式會將其解釋為 ISO-8859-1。

此函式不會引發異常。

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

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

對兩個 Unicode 字串進行富比較，並返回以下值之一：

• 如果引發了異常，則返回 NULL

• 如果比較成功，則返回 Py_True 或 Py_False

• 如果型別組合未知，則返回 Py_NotImplemented

op 的可能值包括 Py_GT、Py_GE、Py_EQ、Py_NE、Py_LT 和 Py_LE。

PyObject *PyUnicode_Format(PyObject *format, PyObject *args)

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

從 format 和 args 返回一個新的字串物件；這類似於 format % args。

int PyUnicode_Contains(PyObject *unicode, PyObject *substr)

屬於 穩定 ABI 的一部分。

檢查 substr 是否包含在 unicode 中，並相應地返回 true 或 false。

substr 必須強制轉換為一個元素的 Unicode 字串。如果發生錯誤，則返回 -1。

void PyUnicode_InternInPlace(PyObject **p_unicode)

屬於 穩定 ABI 的一部分。

原地實習引數 *p_unicode。該引數必須是指向 Python Unicode 字串物件的指標變數的地址。如果存在與 *p_unicode 相同的已實習字串，則將其設定為 *p_unicode (釋放對舊字串物件的引用，並建立一個對已實習字串物件的新的強引用)，否則保持 *p_unicode 不變並進行實習。

（澄清：即使有很多關於引用的討論，也可以將此函式視為引用中立的。你必須擁有你傳入的物件；呼叫後，你不再擁有傳入的引用，但你新擁有了結果。）

此函式永遠不會引發異常。如果出現錯誤，它會在不實習的情況下保持其引數不變。

str 子類的例項可能不會被實習，也就是說，PyUnicode_CheckExact(*p_unicode) 必須為 true。如果不是，那麼與其他任何錯誤一樣，該引數將保持不變。

請注意，實習的字串不是“不朽的”。你必須保留對結果的引用才能從實習中獲益。

PyObject *PyUnicode_InternFromString(const char *str)

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

PyUnicode_FromString() 和 PyUnicode_InternInPlace() 的組合，用於靜態分配的字串。

返回對已實習的新 Unicode 字串物件或具有相同值的早期實習的字串物件的新（“擁有的”）引用。

Python 可能會保留對結果的引用，或者使其不朽，從而阻止其被及時垃圾回收。對於實習大量不同的字串（例如來自使用者輸入的字串），最好直接呼叫 PyUnicode_FromString() 和 PyUnicode_InternInPlace()。

CPython 實現細節： 以這種方式實習的字串被設為不朽的。