Unicode 对象和编解码器¶

Unicode 对象¶

自从 Python 3.3 中实现 PEP 393 以来，Unicode 对象内部使用多种表示形式，以便在内存高效的同时处理完整的 Unicode 字符范围。对于所有码点都低于 128、256 或 65536 的字符串有特殊情况；否则，码点必须低于 1114112（这是完整的 Unicode 范围）。

UTF-8 表示是按需创建并缓存在 Unicode 对象中的。

备注

Py_UNICODE 表示已在 Python 3.12 中随弃用的 API 一起移除。有关更多信息，请参阅 PEP 623。

Unicode 类型¶

这些是 Python 中用于 Unicode 实现的基本 Unicode 对象类型

PyTypeObject PyUnicode_Type¶: 作为稳定 ABI 的一部分。
此 PyTypeObject 实例表示 Python Unicode 类型。它以 str 的形式暴露给 Python 代码。

PyTypeObject PyUnicodeIter_Type¶: 作为稳定 ABI 的一部分。
此 PyTypeObject 实例表示 Python Unicode 迭代器类型。它用于迭代 Unicode 字符串对象。

type Py_UCS4¶
type Py_UCS2¶
type Py_UCS1¶: 作为稳定 ABI 的一部分。
这些类型是分别用于包含 32 位、16 位和 8 位字符的无符号整数类型的 typedef。处理单个 Unicode 字符时，请使用 Py_UCS4。

在 3.3 版本加入。

type PyASCIIObject¶
type PyCompactUnicodeObject¶
type PyUnicodeObject¶: 这些 PyObject 的子类型表示 Python Unicode 对象。在几乎所有情况下，它们都不应直接使用，因为所有处理 Unicode 对象的 API 函数都接受并返回 PyObject 指针。

在 3.3 版本加入。

以下 API 是 C 宏和静态内联函数，用于对 Unicode 对象的内部只读数据进行快速检查和访问

int PyUnicode_Check(PyObject *obj)¶: 如果对象 obj 是 Unicode 对象或 Unicode 子类型的实例，则返回 True。此函数始终成功。

int PyUnicode_CheckExact(PyObject *obj)¶: 如果对象 obj 是 Unicode 对象，但不是子类型的实例，则返回 True。此函数始终成功。

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 类型常量（见上文），该常量指示此 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)¶

将码点 value 写入字符串中给定的零基 index。

kind 值和 data 指针必须分别通过 PyUnicode_KIND() 和 PyUnicode_DATA() 从字符串中获取。在调用 PyUnicode_WRITE() 时，您必须持有该字符串的引用。所有 PyUnicode_WriteChar() 的要求也适用。

此函数对其任何要求都不执行检查，旨在用于循环。

在 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 创建另一个字符串的最大码点，unicode 必须采用“规范”表示形式。这始终是一个近似值，但比迭代字符串更高效。

在 3.3 版本加入。

int PyUnicode_IsIdentifier(PyObject *unicode)¶: 作为稳定 ABI 的一部分。
如果字符串根据语言定义（名称 (标识符和关键字) 节）是有效标识符，则返回 1。否则返回 0。

3.9 版本中的变化: 如果字符串未就绪，函数不再调用 Py_FatalError()。

unsigned int PyUnicode_IS_ASCII(PyObject *unicode)¶: 如果字符串只包含 ASCII 字符，则返回 True。等同于 str.isascii()。

在 3.2 版本加入。

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 是否为可打印字符（如同 str.isprintable() 的含义），返回 1 或 0。

这些 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)¶: 返回转换为双精度的字符 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 中最接近的值。

如果出错，则设置异常并返回 NULL。

创建后，字符串可以通过 PyUnicode_WriteChar()、PyUnicode_CopyCharacters()、PyUnicode_Fill()、PyUnicode_WRITE() 或类似函数填充。由于字符串应该是不可变的，因此在修改时请注意不要“使用”结果。特别是，在填充其最终内容之前，字符串

不得哈希，
不得 转换为 UTF-8 或其他非“规范”表示形式，
不得更改其引用计数，
不得与可能执行上述操作的代码共享。

此列表并非详尽无遗。避免这些用法是您的责任；Python 并不总是检查这些要求。

为避免意外暴露部分写入的字符串对象，请优先使用 PyUnicodeWriter API，或以下 PyUnicode_From* 函数之一。

在 3.3 版本加入。

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

返回值：新引用。

使用给定的 kind 创建一个新的 Unicode 对象（可能的值是 PyUnicode_1BYTE_KIND 等，由 PyUnicode_KIND() 返回）。buffer 必须指向一个包含 size 个单位的数组，每个字符 1、2 或 4 字节，由 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 的一部分。

从 char 缓冲区 str 创建一个 Unicode 对象。字节将被解释为 UTF-8 编码。缓冲区被复制到新对象中。返回值可能是一个共享对象，即不允许修改数据。

此函数在以下情况下引发 SystemError：

大小 < 0,
str 为 NULL 且 size > 0

3.12 版本中的变化: str == NULL 且 size > 0 不再允许。

PyObject *PyUnicode_FromString(const char *str)¶: 返回值: 新引用。 稳定ABI 的一部分。
从 UTF-8 编码的以 null 结尾的 char 缓冲区 str 创建一个 Unicode 对象。

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

返回值: 新引用。 稳定ABI 的一部分。

接受一个 C printf() 风格的 format 字符串和可变数量的参数，计算结果 Python Unicode 字符串的大小，并返回一个将值格式化到其中的字符串。可变参数必须是 C 类型，并且必须与 format ASCII 编码字符串中的格式字符完全对应。

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

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

转换标志字符是

Flag	含义
`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*。

转换说明符是

转换说明符	类型	注释
`%`	不适用	字面量 `%` 字符。
`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"（如果使用了长度修饰符 l）的字节数或 wchar_t 项数（如果 PyObject* 参数为 NULL），以及 "%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_FromOrdinal(int ordinal)¶

返回值: 新引用。 稳定ABI 的一部分。

从给定的 Unicode 码点 ordinal 创建一个 Unicode 对象。

序数必须在 range(0x110000) 中。如果不在，则会引发 ValueError。

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

返回值: 新引用。 稳定ABI 的一部分。

将编码对象 obj 解码为 Unicode 对象。

bytes、bytearray 和其他 bytes-like objects 根据给定的 encoding 和 errors 定义的错误处理进行解码。两者都可以是 NULL，以便接口使用默认值（有关详细信息，请参阅内置编解码器）。

所有其他对象，包括 Unicode 对象，都会导致设置 TypeError。

如果发生错误，API 返回 NULL。调用者负责减少返回对象的引用计数。

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

作为稳定 ABI 的一部分。

将字符串 right 附加到 p_left 的末尾。p_left 必须指向 Unicode 对象的强引用；PyUnicode_Append() 释放（“窃取”）此引用。

如果出错，将 *p_left 设置为 NULL 并设置异常。

如果成功，将 *p_left 设置为结果的新强引用。

void PyUnicode_AppendAndDel(PyObject **p_left, PyObject *right)¶: 作为稳定 ABI 的一部分。
此函数类似于 PyUnicode_Append()，唯一的区别是它将 right 的引用计数减一。

PyObject *PyUnicode_BuildEncodingMap(PyObject *string)¶: 返回值: 新引用。 稳定ABI 的一部分。
返回适合解码自定义单字节编码的映射。给定一个最多 256 个字符的 Unicode 字符串 string，表示一个编码表，返回一个紧凑的内部映射对象或一个将字符序数映射到字节值的字典。在无效输入时引发 TypeError 并返回 NULL。

在 3.2 版本加入。

const char *PyUnicode_GetDefaultEncoding(void)¶

作为稳定 ABI 的一部分。

返回默认字符串编码的名称，即 "utf-8"。请参阅 sys.getdefaultencoding()。

返回的字符串无需释放，并且在解释器关闭之前有效。

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 并设置异常，否则返回复制的字符数。

字符串不得已被“使用”。有关详细信息，请参阅 PyUnicode_New()。

在 3.3 版本加入。

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

作为稳定 ABI 的一部分。

将 Unicode 对象 *unicode 的大小调整为新的 length（以码点为单位）。

尝试就地调整字符串大小（通常比分配新字符串并复制字符更快），或创建新字符串。

*unicode 被修改为指向新的（已调整大小的）对象，成功时返回 0。否则，返回 -1 并设置异常，*unicode 保持不变。

该函数不检查字符串内容，结果可能不是规范表示形式的字符串。

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，则失败。

字符串不得已被“使用”。有关详细信息，请参阅 PyUnicode_New()。

返回写入的字符数，如果出错则返回 -1 并引发异常。

在 3.3 版本加入。

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

自 3.7 版本起成为稳定ABI 的一部分。

将 character 写入字符串 unicode 中零基 index 处。成功时返回 0，出错时返回 -1 并设置异常。

此函数检查 unicode 是否为 Unicode 对象，索引是否未越界，以及对象的引用计数是否为一。请参阅 PyUnicode_WRITE() 以获取跳过这些检查的版本，使这些检查成为您的责任。

字符串不得已被“使用”。有关详细信息，请参阅 PyUnicode_New()。

在 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 设置，则包含一个 null 字符。如果发生错误，返回 NULL 并设置异常（特别是，如果 buflen 小于 unicode 的长度，则为 SystemError）。成功时返回 buffer。

在 3.3 版本加入。

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *unicode)¶: 自 3.7 版本起成为稳定ABI 的一部分。
将字符串 unicode 复制到使用 PyMem_Malloc() 分配的新 UCS4 缓冲区中。如果失败，返回 NULL 并设置 MemoryError。返回的缓冲区总是附加一个额外的 null 码点。

在 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 必须以 null 字符结尾，但不能包含嵌入的 null 字符。

使用 PyUnicode_DecodeFSDefaultAndSize() 从文件系统编码和错误处理程序解码字符串。

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

参见

Py_DecodeLocale() 函数。

在 3.3 版本加入。

版本 3.7 中的更改: 现在，除 Android 外，该函数还为 surrogateescape 错误处理程序使用当前区域设置编码。以前，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 不能包含嵌入的 null 字符。

使用 PyUnicode_EncodeFSDefault() 将字符串编码为文件系统编码和错误处理程序。

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

参见

Py_EncodeLocale() 函数。

在 3.3 版本加入。

版本 3.7 中的更改: 现在，除 Android 外，该函数还为 surrogateescape 错误处理程序使用当前区域设置编码。以前，Py_EncodeLocale() 用于 surrogateescape，而当前区域设置编码用于 strict。

文件系统编码¶

对文件系统编码和错误处理程序 (PEP 383 和 PEP 529) 进行编码和解码的函数。

在参数解析期间将文件名编码为 bytes 时，应使用 "O&" 转换器，并将 PyUnicode_FSConverter() 作为转换函数传递

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

作为稳定 ABI 的一部分。

PyArg_Parse* 转换器: 使用 PyUnicode_EncodeFSDefault() 将 str 对象（直接或通过 os.PathLike 接口获得）编码为 bytes；bytes 对象按原样输出。result 必须是类型为 PyObject*（或 PyBytesObject*）的 C 变量的地址。成功时，将变量设置为对字节对象的新强引用，该引用在不再使用时必须释放，并返回非零值 (Py_CLEANUP_SUPPORTED)。结果中不允许嵌入 null 字节。失败时，返回 0 并设置异常。

如果 obj 为 NULL，函数将释放 result 指向的变量中存储的强引用并返回 1。

在 3.1 版本加入。

在 3.6 版本发生变更: 接受 path-like object。

在参数解析期间将文件名解码为 str 时，应使用 "O&" 转换器，并将 PyUnicode_FSDecoder() 作为转换函数传递

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

作为稳定 ABI 的一部分。

PyArg_Parse* 转换器: 使用 PyUnicode_DecodeFSDefaultAndSize() 将 bytes 对象（直接或间接通过 os.PathLike 接口获得）解码为 str；str 对象按原样输出。result 必须是类型为 PyObject*（或 PyUnicodeObject*）的 C 变量的地址。成功时，将变量设置为对 Unicode 对象的新强引用，该引用在不再使用时必须释放，并返回非零值 (Py_CLEANUP_SUPPORTED)。结果中不允许嵌入 null 字符。失败时，返回 0 并设置异常。

如果 obj 为 NULL，释放对 result 指向的对象的强引用并返回 1。

在 3.2 版本加入。

在 3.6 版本发生变更: 接受 path-like object。

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 都接受编码和错误这两个参数，它们与内置的 str() 字符串对象构造函数中的同名参数具有相同的语义。

将编码设置为 NULL 会导致使用默认编码 UTF-8。文件系统调用应使用 PyUnicode_FSConverter() 对文件名进行编码。这在内部使用文件系统编码和错误处理程序。

错误处理由 errors 设置，也可以设置为 NULL，这意味着使用编解码器定义的默认处理。所有内置编解码器的默认错误处理都是“严格”（引发 ValueError）。

所有编解码器都使用相似的接口。为简单起见，仅记录了与以下通用接口的偏差。

通用编解码器¶

提供以下宏

Py_UNICODE_REPLACEMENT_CHARACTER¶

Unicode 码点 U+FFFD (替换字符)。

如果 errors 参数设置为“替换”，此 Unicode 字符将用作解码期间的替换字符。

这些是通用编解码器 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 字节对象返回。错误处理是“严格”的。如果编解码器引发异常，则返回 NULL。

如果字符串包含代理码点（U+D800 - U+DFFF），则函数失败。

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

自 3.10 版本以来，作为稳定 ABI 的一部分。

返回指向 Unicode 对象的 UTF-8 编码的指针，并将编码表示的大小（以字节为单位）存储在 size 中。size 参数可以为 NULL；在这种情况下，不会存储大小。返回的缓冲区总是附加一个额外的 null 字节（不包含在 size 中），无论是否存在其他 null 码点。

发生错误时，设置异常，将 size 设置为 -1 (如果它不为 NULL) 并返回 NULL。

如果字符串包含代理码点（U+D800 - U+DFFF），则函数失败。

这会将字符串的 UTF-8 表示缓存到 Unicode 对象中，后续调用将返回指向同一缓冲区的指针。调用方无需负责释放缓冲区。当 Unicode 对象被垃圾回收时，缓冲区将被释放，指向它的指针将失效。

在 3.3 版本加入。

版本 3.7 中的更改: 返回类型现在是 const char * 而不是 char *。

版本 3.10 中的更改: 此函数是受限 C API 的一部分。

const char *PyUnicode_AsUTF8(PyObject *unicode)¶: 与 PyUnicode_AsUTF8AndSize() 相同，但不存储大小。

警告

此函数对嵌入在 unicode 中的空字符没有特殊行为。因此，包含空字符的字符串将保留在返回的字符串中，某些 C 函数可能会将其解释为字符串的结尾，从而导致截断。如果截断是一个问题，建议使用 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）定义错误处理。它默认为“严格”。

如果 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 字节序列（例如字节数不能被四整除）视为错误。这些字节将不会被解码，并且已解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)¶: 返回值: 新引用。 稳定ABI 的一部分。
使用本机字节序的 UTF-32 编码返回 Python 字节字符串。字符串总是以 BOM 标记开头。错误处理是“严格”的。如果编解码器引发异常，则返回 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）定义错误处理。它默认为“严格”。

如果 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 标记开头。错误处理是“严格”的。如果编解码器引发异常，则返回 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 的一部分。
通过解码 Unicode-Escape 编码字符串 str 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)¶: 返回值: 新引用。 稳定ABI 的一部分。
使用 Unicode-Escape 编码 Unicode 对象，并将结果作为字节对象返回。错误处理是“严格”的。如果编解码器引发异常，则返回 NULL。

Raw-Unicode-Escape 编解码器¶

这些是“原始 Unicode Escape”编解码器 API

PyObject *PyUnicode_DecodeRawUnicodeEscape(const char *str, Py_ssize_t size, const char *errors)¶: 返回值: 新引用。 稳定ABI 的一部分。
通过解码 Raw-Unicode-Escape 编码字符串 str 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)¶: 返回值: 新引用。 稳定ABI 的一部分。
使用 Raw-Unicode-Escape 编码 Unicode 对象，并将结果作为字节对象返回。错误处理是“严格”的。如果编解码器引发异常，则返回 NULL。

Latin-1 编解码器¶

这些是 Latin-1 编解码器 API：Latin-1 对应于前 256 个 Unicode 序数，并且编解码器在编码期间只接受这些序数。

PyObject *PyUnicode_DecodeLatin1(const char *str, Py_ssize_t size, const char *errors)¶: 返回值: 新引用。 稳定ABI 的一部分。
通过解码 Latin-1 编码字符串 str 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)¶: 返回值: 新引用。 稳定ABI 的一部分。
使用 Latin-1 编码 Unicode 对象，并将结果作为 Python 字节对象返回。错误处理是“严格”的。如果编解码器引发异常，则返回 NULL。

ASCII 编解码器¶

这些是 ASCII 编解码器 API。只接受 7 位 ASCII 数据。所有其他代码都会生成错误。

PyObject *PyUnicode_DecodeASCII(const char *str, Py_ssize_t size, const char *errors)¶: 返回值: 新引用。 稳定ABI 的一部分。
通过解码 ASCII 编码字符串 str 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)¶: 返回值: 新引用。 稳定ABI 的一部分。
使用 ASCII 编码 Unicode 对象，并将结果作为 Python 字节对象返回。错误处理是“严格”的。如果编解码器引发异常，则返回 NULL。

字符映射编解码器¶

此编解码器很特殊，因为它可用于实现许多不同的编解码器（实际上，大多数包含在 encodings 包中的标准编解码器都是通过这种方式实现的）。该编解码器使用映射来编码和解码字符。所提供的映射对象必须支持 __getitem__() 映射接口；字典和序列运行良好。

以下是映射编解码器 API

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

返回值: 新引用。 稳定ABI 的一部分。

通过使用给定的 mapping 对象解码编码字符串 str 的 size 字节来创建 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_DecodeCodePageStateful(int code_page, const char *str, Py_ssize_t size, const char *errors, Py_ssize_t *consumed)¶: 返回值：新引用。 自 3.7 版本起，作为 Windows 上稳定 ABI 的一部分。
类似于 PyUnicode_DecodeMBCSStateful()，但使用 code_page 指定的代码页。

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 次拆分。如果为负数，则不设置限制。分隔符不包含在结果列表中。

如果出错，则返回 NULL 并设置异常。

等同于 str.split()。

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

返回值: 新引用。 稳定ABI 的一部分。

类似于 PyUnicode_Split()，但拆分将从字符串末尾开始进行。

如果出错，则返回 NULL 并设置异常。

等同于 str.rsplit()。

PyObject *PyUnicode_Splitlines(PyObject *unicode, int keepends)¶: 返回值: 新引用。 稳定ABI 的一部分。
将 Unicode 字符串按行分隔符拆分，返回一个 Unicode 字符串列表。CRLF 被视为一个行分隔符。如果 keepends 为 0，则行分隔符不包含在结果字符串中。

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

返回值: 新引用。 稳定ABI 的一部分。

将 Unicode 字符串在 sep 的第一次出现处拆分，并返回一个 3 元组，其中包含分隔符之前的部分、分隔符本身以及分隔符之后的部分。如果未找到分隔符，则返回一个 3 元组，其中包含字符串本身，后跟两个空字符串。

sep 不得为空。

如果出错，则返回 NULL 并设置异常。

等同于 str.partition()。

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

返回值: 新引用。 稳定ABI 的一部分。

类似于 PyUnicode_Partition()，但将 Unicode 字符串在 sep 的最后一次出现处拆分。如果未找到分隔符，则返回一个 3 元组，其中包含两个空字符串，后跟字符串本身。

sep 不得为空。

如果出错，则返回 NULL 并设置异常。

等同于 str.rpartition()。

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] 匹配（direction == -1 表示前缀匹配，direction == 1 表示后缀匹配），则返回 1，否则返回 0。如果发生错误，则返回 -1。

Py_ssize_t PyUnicode_Find(PyObject *unicode, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction)¶: 作为稳定 ABI 的一部分。
使用给定的 direction（direction == 1 表示向前搜索，direction == -1 表示向后搜索）返回 substr 在 unicode[start:end] 中的第一个位置。返回值是第一个匹配项的索引；值 -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（direction == 1 表示向前搜索，direction == -1 表示向后搜索）返回字符 ch 在 unicode[start:end] 中的第一个位置。返回值是第一个匹配项的索引；值 -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() 来检查错误。

参见

PyUnicode_Equal() 函数。

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

自 3.14 版本以来，作为稳定 ABI 的一部分。

测试两个字符串是否相等

如果 a 等于 b，则返回 1。
如果 a 不等于 b，则返回 0。
如果 a 或 b 不是 str 对象，则设置 TypeError 异常并返回 -1。

如果 a 和 b 是 str 对象，则该函数总是成功的。

该函数适用于 str 子类，但不遵循自定义的 __eq__() 方法。

参见

PyUnicode_Compare() 函数。

在 3.14 版本加入。

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

自 3.13 版本起成为稳定 ABI 的一部分。

比较一个 Unicode 对象与一个 char 缓冲区（该缓冲区被解释为 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 的一部分。

就地intern参数 *p_unicode。该参数必须是指向 Python Unicode 字符串对象的指针变量的地址。如果存在与 *p_unicode 相同的现有interned字符串，则将其设置为 *p_unicode（释放对旧字符串对象的引用并创建对interned字符串对象的新强引用），否则它保持 *p_unicode 不变并intern它。

（澄清：尽管有很多关于引用的讨论，但请将此函数视为引用中立的。您必须拥有传入的对象；调用后，您不再拥有传入的引用，但您新拥有结果。）

此函数从不引发异常。发生错误时，它会保持其参数不变而不进行内部化。

str 子类的实例可能未被内部化，也就是说，PyUnicode_CheckExact(*p_unicode) 必须为真。如果不是，那么——与任何其他错误一样——参数保持不变。

请注意，内部化字符串并非“不朽”。您必须保留对结果的引用才能从内部化中受益。

PyObject *PyUnicode_InternFromString(const char *str)¶

返回值: 新引用。 稳定ABI 的一部分。

PyUnicode_FromString() 和 PyUnicode_InternInPlace() 的组合，适用于静态分配的字符串。

返回对已内部化的新 Unicode 字符串对象或具有相同值的早期内部化字符串对象的新（“拥有”）引用。

Python 可能会保留对结果的引用，或使其不朽，从而阻止其及时进行垃圾回收。对于内部化无限数量的不同字符串（例如来自用户输入的字符串），请优先直接调用 PyUnicode_FromString() 和 PyUnicode_InternInPlace()。

unsigned int PyUnicode_CHECK_INTERNED(PyObject *str)¶: 如果 str 已内部化，则返回非零值，否则返回零。str 参数必须是字符串；不进行此检查。此函数总是成功的。

CPython 实现细节: 非零返回值可能包含有关字符串如何内部化的附加信息。此类非零值的含义以及每个特定字符串的内部化相关细节可能会在 CPython 版本之间发生变化。

PyUnicodeWriter¶

PyUnicodeWriter API 可用于创建 Python str 对象。

在 3.14 版本加入。

type PyUnicodeWriter¶

一个 Unicode 写入器实例。

该实例必须在成功时通过 PyUnicodeWriter_Finish() 销毁，或在错误时通过 PyUnicodeWriter_Discard() 销毁。

PyUnicodeWriter *PyUnicodeWriter_Create(Py_ssize_t length)¶

创建一个 Unicode 写入器实例。

length 必须大于或等于 0。

如果 length 大于 0，则预分配一个 length 字符的内部缓冲区。

设置异常并在出错时返回 NULL。

PyObject *PyUnicodeWriter_Finish(PyUnicodeWriter *writer)¶

返回最终的 Python str 对象并销毁写入器实例。

设置异常并在出错时返回 NULL。

此调用后，写入器实例无效。

void PyUnicodeWriter_Discard(PyUnicodeWriter *writer)¶

丢弃内部 Unicode 缓冲区并销毁写入器实例。

如果 writer 为 NULL，则不执行任何操作。

此调用后，写入器实例无效。

int PyUnicodeWriter_WriteChar(PyUnicodeWriter *writer, Py_UCS4 ch)¶

将单个 Unicode 字符 ch 写入 writer。