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 编码字符串中的格式字符完全对应。

转换说明符包含两个或多个字符，并具有以下组成部分，这些组成部分必须按此顺序出现：

标记说明符开始的 '%' 字符。
转换标志（可选），会影响某些转换类型的结果。
最小字段宽度（可选）。如果指定为 '*' （星号），则实际宽度在下一个参数中给出，该参数必须是 int 类型，并且要转换的对象在最小字段宽度和可选精度之后。
精度（可选），以 '.' （点）后跟精度给出。如果指定为 '*' （星号），则实际精度在下一个参数中给出，该参数必须是 int 类型，并且要转换的值在精度之后。
长度修饰符（可选）。
转换类型。

转换标志字符是：

标志	含义
`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 实现细节： 以这种方式实习的字符串被设为不朽的。

Unicode 对象和编解码器¶

Unicode 对象¶

Unicode 类型¶

Unicode 字符属性¶

创建和访问 Unicode 字符串¶

区域设置编码¶

文件系统编码¶

wchar_t 支持¶

内置编解码器¶

通用编解码器¶

UTF-8 编解码器¶

UTF-32 编解码器¶

UTF-16 编解码器¶

UTF-7 编解码器¶

Unicode-Escape 编解码器¶

Raw-Unicode-Escape 编解码器¶

Latin-1 编解码器¶

ASCII 编解码器¶

字符映射编解码器¶

用于 Windows 的 MBCS 编解码器¶

方法 & 插槽¶

方法和插槽函数¶

目录

上一主题

下一主题

本页