Unicode 对象和编解码器

Unicode 对象

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

Py_UNICODE* 和 UTF-8 表示按需创建并缓存在 Unicode 对象中。 Py_UNICODE* 表示已被弃用且效率低下；在性能或内存敏感的情况下应该避免使用它。

由于旧 API 和新 API 之间的转换，unicode 对象在内部可以处于两种状态，具体取决于它们的创建方式：

“规范” unicode 对象是由未弃用的 unicode API 创建的所有对象。它们使用实现所允许的最有效的表示。
“遗留” unicode 对象是通过其中一个不推荐使用的 API（通常是 PyUnicode_FromUnicode()）创建的，并且只带有 Py_UNICODE* 表示；在调用任何其他 API 之前，您必须对它们调用 PyUnicode_READY()。

Unicode 类型

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

type Py_UCS4 type Py_UCS2 type Py_UCS1: 这些类型是无符号整数类型的 typedef，其宽度足以分别包含 32 位、16 位和 8 位字符。处理单个Unicode字符时，使用Py_UCS4。

3.3 版中的新功能。

type Py_UNICODE: 这是一个 wchar_t 的 typedef，根据平台是 16 位类型还是 32 位类型。

3.3 版更改：在以前的版本中，这是 16 位类型还是 32 位类型，具体取决于您在构建时选择了“窄”还是“宽” Unicode 版本的 Python。

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

3.3 版中的新功能。

PyTypeObject PyUnicode_Type

PyTypeObject 的这个实例表示 Python Unicode 类型。它以 str 的形式暴露给 Python 代码。

以下 API 是真正的 C 宏，可用于进行快速检查和访问 Unicode 对象的内部只读数据：

int PyUnicode_Check(PyObject *o)

如果对象 o 是 Unicode 对象或 Unicode 子类型的实例，则返回 true。

int PyUnicode_CheckExact(PyObject *o)

如果对象 o 是 Unicode 对象，但不是子类型的实例，则返回 true。

int PyUnicode_READY(PyObject *o)

确保字符串对象 o 在“规范”表示中。在使用下面描述的任何访问宏之前，这是必需的。

成功时返回 0，失败时返回 -1 并设置异常，尤其是在内存分配失败时。

3.3 版中的新功能。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *o): 返回 Unicode 字符串的长度，以代码点为单位。 o 必须是“规范”表示中的 Unicode 对象（未选中）。

3.3 版中的新功能。

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *o) Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *o) Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *o): 返回一个指向转换为 UCS1、UCS2 或 UCS4 整数类型的规范表示的指针，以进行直接字符访问。如果规范表示具有正确的字符大小，则不会执行任何检查；使用 PyUnicode_KIND() 选择正确的宏。确保在访问它之前已经调用了 PyUnicode_READY()。

3.3 版中的新功能。

PyUnicode_WCHAR_KIND PyUnicode_1BYTE_KIND PyUnicode_2BYTE_KIND PyUnicode_4BYTE_KIND: 返回 PyUnicode_KIND() 宏的值。

3.3 版中的新功能。

int PyUnicode_KIND(PyObject *o): 返回 PyUnicode 类型常量之一（见上文），指示此 Unicode 对象用于存储其数据的每个字符的字节数。 o 必须是“规范”表示中的 Unicode 对象（未选中）。

3.3 版中的新功能。

void *PyUnicode_DATA(PyObject *o): 返回指向原始 unicode 缓冲区的空指针。 o 必须是“规范”表示中的 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 *o, Py_ssize_t index): 从 Unicode 对象 o 中读取字符，该对象必须采用“规范”表示。如果您进行多次连续读取，这比 PyUnicode_READ() 效率低。

3.3 版中的新功能。

PyUnicode_MAX_CHAR_VALUE(PyObject *o): 返回适合基于 o 创建另一个字符串的最大代码点，该字符串必须采用“规范”表示。这始终是一个近似值，但比迭代字符串更有效。

3.3 版中的新功能。

int PyUnicode_ClearFreeList()

清除空闲列表。返回已释放项目的总数。

Py_ssize_t PyUnicode_GET_SIZE(PyObject *o)

返回已弃用的 Py_UNICODE 表示的大小，以代码单元为单位（这包括作为 2 个单元的代理对）。 o 必须是 Unicode 对象（未选中）。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o)

以字节为单位返回已弃用的 Py_UNICODE 表示的大小。 o 必须是 Unicode 对象（未选中）。

Py_UNICODE *PyUnicode_AS_UNICODE(PyObject *o) const char *PyUnicode_AS_DATA(PyObject *o): 返回指向对象的 Py_UNICODE 表示的指针。返回的缓冲区总是以一个额外的空代码点终止。它还可能包含嵌入的空代码点，这将导致在大多数 C 函数中使用时字符串被截断。 AS_DATA 形式将指针转换为 const char *。 o 参数必须是一个 Unicode 对象（未检查）。

3.3 版更改：这个宏现在效率低下——因为在许多情况下 Py_UNICODE 表示不存在并且需要创建——并且可能失败（返回 NULL ] 与例外集）。尝试移植代码以使用新的 PyUnicode_nBYTE_DATA() 宏或使用 PyUnicode_WRITE() 或 PyUnicode_READ()。

Unicode 字符属性

Unicode 提供了许多不同的字符属性。最常需要的可通过这些宏获得，这些宏根据 Python 配置映射到 C 函数。

int Py_UNICODE_ISSPACE(Py_UNICODE ch)

根据 ch 是否为空白字符，返回 1 或 0。

int Py_UNICODE_ISLOWER(Py_UNICODE ch)

根据 ch 是否为小写字符，返回 1 或 0。

int Py_UNICODE_ISUPPER(Py_UNICODE ch)

根据 ch 是否为大写字符，返回 1 或 0。

int Py_UNICODE_ISTITLE(Py_UNICODE ch)

根据 ch 是否是标题字符，返回 1 或 0。

int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch)

根据 ch 是否为换行符，返回 1 或 0。

int Py_UNICODE_ISDECIMAL(Py_UNICODE ch)

根据 ch 是否为十进制字符，返回 1 或 0。

int Py_UNICODE_ISDIGIT(Py_UNICODE ch)

根据 ch 是否为数字字符，返回 1 或 0。

int Py_UNICODE_ISNUMERIC(Py_UNICODE ch)

根据 ch 是否为数字字符，返回 1 或 0。

int Py_UNICODE_ISALPHA(Py_UNICODE ch)

根据 ch 是否为字母字符，返回 1 或 0。

int Py_UNICODE_ISALNUM(Py_UNICODE ch)

根据 ch 是否为字母数字字符，返回 1 或 0。

int Py_UNICODE_ISPRINTABLE(Py_UNICODE ch)

根据 ch 是否为可打印字符，返回 1 或 0。不可打印字符是在 Unicode 字符数据库中定义为“其他”或“分隔符”的字符，但被认为可打印的 ASCII 空格 (0x20) 除外。（请注意，此上下文中的可打印字符是在字符串上调用 repr() 时不应转义的字符。它与处理写入 sys.stdout 或 sys.stderr 的字符串无关。）

这些 API 可用于快速直接字符转换：

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch): 返回转换为小写的字符 ch。

自 3.3 版起已弃用：此函数使用简单的大小写映射。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch): 返回转换为大写的字符 ch。

自 3.3 版起已弃用：此函数使用简单的大小写映射。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch): 返回转换为标题大小写的字符 ch。

自 3.3 版起已弃用：此函数使用简单的大小写映射。

int Py_UNICODE_TODECIMAL(Py_UNICODE ch)

返回转换为十进制正整数的字符 ch。如果这是不可能的，则返回 -1。此宏不会引发异常。

int Py_UNICODE_TODIGIT(Py_UNICODE ch)

返回字符 ch 转换为一位整数。如果这是不可能的，则返回 -1。此宏不会引发异常。

double Py_UNICODE_TONUMERIC(Py_UNICODE ch)

返回转换为双精度的字符 ch。如果这是不可能的，则返回 -1.0。此宏不会引发异常。

这些 API 可用于代理：

Py_UNICODE_IS_SURROGATE(ch)

检查 ch 是否是代理 (0xD800 <= ch <= 0xDFFF)。

Py_UNICODE_IS_HIGH_SURROGATE(ch)

检查 ch 是否为高代理 (0xD800 <= ch <= 0xDBFF)。

Py_UNICODE_IS_LOW_SURROGATE(ch)

检查 ch 是否为低代理 (0xDC00 <= ch <= 0xDFFF)。

Py_UNICODE_JOIN_SURROGATES(high, low)

连接两个代理字符并返回一个 Py_UCS4 值。 high 和 low 分别是代理对中的前导和尾随代理。

创建和访问 Unicode 字符串

要创建 Unicode 对象并访问它们的基本序列属性，请使用以下 API：

PyObject *PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)

创建一个新的 Unicode 对象。 maxchar 应该是放置在字符串中的真正最大代码点。作为近似值，它可以四舍五入到序列 127、255、65535、1114111 中最接近的值。

这是分配新 Unicode 对象的推荐方法。使用此函数创建的对象不可调整大小。

3.3 版中的新功能。

PyObject *PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size): 使用给定的 kind 创建一个新的 Unicode 对象（可能的值是 PyUnicode_1BYTE_KIND 等，由 PyUnicode_KIND() 返回）。 buffer 必须指向每个字符 1、2 或 4 个字节的 size 单位数组，由种类给出。

3.3 版中的新功能。

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

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

如果 u 是 NULL，则此函数的行为类似于 PyUnicode_FromUnicode()，缓冲区设置为 NULL。这种用法已被弃用，取而代之的是 PyUnicode_New()。

PyObject *PyUnicode_FromString(const char *u)

从 UTF-8 编码的空终止字符缓冲区 u 创建一个 Unicode 对象。

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

取一个 C printf() 样式的 format 字符串和可变数量的参数，计算生成的 Python unicode 字符串的大小并返回一个字符串，其中包含格式化的值。变量参数必须是 C 类型，并且必须与 format ASCII 编码字符串中的格式字符完全对应。允许使用以下格式字符：

格式字符	类型	评论
`%%`	不适用	The literal % character.
`%c`	整数	单个字符，表示为 C int。
`%d`	整数	完全等同于 `printf("%d")`。
`%u`	无符号整数	完全等同于 `printf("%u")`。
`%ld`	长	完全等同于 `printf("%ld")`。
`%li`	长	完全等同于 `printf("%li")`。
`%lu`	无符号长	完全等同于 `printf("%lu")`。
`%lld`	长长的	完全等同于 `printf("%lld")`。
`%lli`	长长的	完全等同于 `printf("%lli")`。
`%llu`	无符号长长	完全等同于 `printf("%llu")`。
`%zd`	py_ssize_t	完全等同于 `printf("%zd")`。
`%zi`	py_ssize_t	完全等同于 `printf("%zi")`。
`%zu`	尺寸_t	完全等同于 `printf("%zu")`。
`%i`	整数	完全等同于 `printf("%i")`。
`%x`	整数	完全等同于 `printf("%x")`。
`%s`	字符*	以空字符结尾的 C 字符数组。
`%p`	空白*	C 指针的十六进制表示。大部分等同于 `printf("%p")`，除了它保证以文字 `0x` 开头，而不管平台的 `printf` 产生什么。
`%A`	对象*	调用 ascii() 的结果。
`%U`	对象*	一个 Unicode 对象。
`%V`	PyObject, 字符	一个 unicode 对象（可能是 NULL）和一个以空字符结尾的 C 字符数组作为第二个参数（如果第一个参数是 NULL，将使用它）。
`%S`	对象*	调用 PyObject_Str() 的结果。
`%R`	对象*	调用 PyObject_Repr() 的结果。

无法识别的格式字符会导致格式字符串的所有其余部分按原样复制到结果字符串，并丢弃任何额外的参数。

笔记

宽度格式化单元是字符数而不是字节数。精度格式器单位是 "%s" 和 "%V" 的字节数（如果 PyObject* 参数为 NULL），以及 "%A" 的字符数，[ X155X]、"%S"、"%R" 和 "%V"（如果 PyObject* 参数不为 NULL）。

3.2 版更改：添加了对 "%lld" 和 "%llu" 的支持。

3.3 版更改：添加了对 "%li"、"%lli" 和 "%zi" 的支持。

3.4 版更改：支持 "%s"、"%A"、"%U"、"%V"、"%S"的宽度和精度格式器]、"%R" 添加。

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

与 PyUnicode_FromFormat() 相同，只是它只需要两个参数。

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

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

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

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

如果出现错误，API 将返回 NULL。调用者负责定义返回的对象。

Py_ssize_t PyUnicode_GetLength(PyObject *unicode): 返回 Unicode 对象的长度，以代码点为单位。

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 对象复制到另一个。此函数在必要时执行字符转换，并在可能的情况下回退到 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)

将字符写入字符串。该字符串必须是通过 PyUnicode_New() 创建的。由于 Unicode 字符串应该是不可变的，因此字符串不能被共享，或者已经被散列。

该函数检查 unicode 是一个 Unicode 对象，索引没有越界，并且该对象可以安全地修改（即它的引用计数是一）。

3.3 版中的新功能。

Py_UCS4 PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index): 从字符串中读取一个字符。与宏版本 PyUnicode_READ_CHAR() 相比，此函数检查 unicode 是一个 Unicode 对象并且索引没有越界。

3.3 版中的新功能。

PyObject *PyUnicode_Substring(PyObject *str, Py_ssize_t start, Py_ssize_t end): 返回 str 的子字符串，从字符索引 start（包含）到字符索引 end（不包含）。不支持负索引。

3.3 版中的新功能。

Py_UCS4 *PyUnicode_AsUCS4(PyObject *u, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null): 如果设置了 copy_null，则将字符串 u 复制到 UCS4 缓冲区中，包括空字符。返回 NULL 并设置错误异常（特别是 SystemError 如果 buflen 小于 u 的长度）。 buffer 成功返回。

3.3 版中的新功能。

Py_UCS4 *PyUnicode_AsUCS4Copy(PyObject *u): 将字符串 u 复制到使用 PyMem_Malloc() 分配的新 UCS4 缓冲区中。如果失败，则返回 NULL 并设置 MemoryError。返回的缓冲区总是附加一个额外的空代码点。

3.3 版中的新功能。

已弃用的 Py_UNICODE API

这些 API 函数随着 PEP 393 的实现而被弃用。扩展模块可以继续使用它们，因为它们不会在 Python 3.x 中被删除，但需要注意它们的使用现在可能会导致性能和内存命中。

PyObject *PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size)

从给定大小的 Py_UNICODE 缓冲区 u 创建一个 Unicode 对象。 u 可能是 NULL 这会导致内容未定义。用户有责任填写所需的数据。缓冲区被复制到新对象中。

如果缓冲区不是 NULL，则返回值可能是共享对象。因此，仅当 u 为 NULL 时，才允许修改生成的 Unicode 对象。

如果缓冲区为 NULL，则在使用任何访问宏（例如 PyUnicode_KIND()）之前，必须在填充字符串内容后调用 PyUnicode_READY()。

请迁移到使用 PyUnicode_FromKindAndData()、PyUnicode_FromWideChar() 或 PyUnicode_New()。

Py_UNICODE *PyUnicode_AsUnicode(PyObject *unicode)

返回一个只读指针，指向 Unicode 对象的内部 Py_UNICODE 缓冲区，或者在出错时返回 NULL。如果对象尚不可用，这将创建对象的 Py_UNICODE* 表示。缓冲区总是以额外的空代码点终止。请注意，生成的 Py_UNICODE 字符串也可能包含嵌入的空代码点，这会导致在大多数 C 函数中使用时该字符串被截断。

请迁移到使用 PyUnicode_AsUCS4()、PyUnicode_AsWideChar()、PyUnicode_ReadChar() 或类似的新 API。

PyObject *PyUnicode_TransformDecimalToASCII(Py_UNICODE *s, Py_ssize_t size)

通过根据十进制值将给定 size 的 Py_UNICODE 缓冲区中的所有十进制数字替换为 ASCII 数字 0-9，创建一个 Unicode 对象。如果发生异常，则返回 NULL。

Py_UNICODE *PyUnicode_AsUnicodeAndSize(PyObject *unicode, Py_ssize_t *size): 与 PyUnicode_AsUnicode() 一样，但也将 Py_UNICODE() 数组长度（不包括额外的空终止符）保存在 size 中。请注意，生成的 Py_UNICODE* 字符串可能包含嵌入的空代码点，这会导致该字符串在大多数 C 函数中使用时被截断。

3.3 版中的新功能。

Py_UNICODE *PyUnicode_AsUnicodeCopy(PyObject *unicode)

创建以空代码点结尾的 Unicode 字符串的副本。返回 NULL 并在内存分配失败时引发 MemoryError 异常，否则返回新分配的缓冲区（使用 PyMem_Free() 释放缓冲区）。请注意，生成的 Py_UNICODE* 字符串可能包含嵌入的空代码点，这会导致该字符串在大多数 C 函数中使用时被截断。

3.2 版中的新功能。

请迁移到使用 PyUnicode_AsUCS4Copy() 或类似的新 API。

Py_ssize_t PyUnicode_GetSize(PyObject *unicode)

返回已弃用的 Py_UNICODE 表示的大小，以代码单元为单位（这包括作为 2 个单元的代理对）。

请迁移到使用 PyUnicode_GetLength()。

PyObject *PyUnicode_FromObject(PyObject *obj)

如有必要，将 Unicode 子类型的实例复制到新的真正 Unicode 对象。如果 obj 已经是真正的 Unicode 对象（不是子类型），则返回引用计数增加的引用。

Unicode 或其子类型以外的对象将导致 TypeError。

语言环境编码

当前区域设置编码可用于解码来自操作系统的文本。

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

从当前语言环境编码解码字符串。支持的错误处理程序是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 是 NULL，则解码器使用 "strict" 错误处理程序。 str 必须以空字符结尾，但不能包含嵌入的空字符。

使用 PyUnicode_DecodeFSDefaultAndSize() 解码来自 Py_FileSystemDefaultEncoding 的字符串（Python 启动时读取的语言环境编码）。

也可以看看

Py_DecodeLocale() 函数。

3.3 版中的新功能。

3.6.5 版更改：该函数现在还使用 surrogateescape 错误处理程序的当前语言环境编码。之前，Py_DecodeLocale()用于surrogateescape，当前区域编码用于strict。

PyObject *PyUnicode_DecodeLocale(const char *str, const char *errors): 类似于 PyUnicode_DecodeLocaleAndSize()，但使用 strlen() 计算字符串长度。

3.3 版中的新功能。

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

将 Unicode 对象编码为当前语言环境编码。支持的错误处理程序是 "strict" 和 "surrogateescape" (PEP 383)。如果 errors 是 NULL，则编码器使用 "strict" 错误处理程序。返回一个 bytes 对象。 unicode 不能包含嵌入的空字符。

使用 PyUnicode_EncodeFSDefault() 将字符串编码为 Py_FileSystemDefaultEncoding（Python 启动时读取的语言环境编码）。

也可以看看

Py_EncodeLocale() 函数。

3.3 版中的新功能。

3.6.5 版更改：该函数现在还使用 surrogateescape 错误处理程序的当前语言环境编码。之前，Py_EncodeLocale()用于surrogateescape，当前区域编码用于strict。

文件系统编码

要对文件名和其他环境字符串进行编码和解码，应使用 Py_FileSystemDefaultEncoding 作为编码，并使用 Py_FileSystemDefaultEncodeErrors 作为错误处理程序 (PEP 383 和 PEP 529）。要在参数解析期间将文件名编码为 bytes，应使用 "O&" 转换器，传递 PyUnicode_FSConverter() 作为转换函数：

int PyUnicode_FSConverter(PyObject *obj, void *result): 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): ParseTuple 转换器：解码 bytes 对象 - 通过 os.PathLike 接口直接或间接获得 - 使用 PyUnicode_DecodeFSDefaultAndSize() 到 str； str 对象按原样输出。 result 必须是 PyUnicodeObject* 不再使用时必须释放。

3.2 版中的新功能。

3.6 版更改：接受类路径对象。

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

使用 Py_FileSystemDefaultEncoding 和 Py_FileSystemDefaultEncodeErrors 错误处理程序解码字符串。

如果未设置 Py_FileSystemDefaultEncoding，则回退到语言环境编码。

Py_FileSystemDefaultEncoding 在启动时从语言环境编码初始化，以后无法修改。如果需要从当前语言环境编码解码字符串，请使用 PyUnicode_DecodeLocaleAndSize()。

也可以看看

Py_DecodeLocale() 函数。

3.6 版更改：使用 Py_FileSystemDefaultEncodeErrors 错误处理程序。

PyObject *PyUnicode_DecodeFSDefault(const char *s)

使用 Py_FileSystemDefaultEncoding 和 Py_FileSystemDefaultEncodeErrors 错误处理程序解码以空字符结尾的字符串。

如果未设置 Py_FileSystemDefaultEncoding，则回退到语言环境编码。

如果您知道字符串长度，请使用 PyUnicode_DecodeFSDefaultAndSize()。

3.6 版更改：使用 Py_FileSystemDefaultEncodeErrors 错误处理程序。

PyObject *PyUnicode_EncodeFSDefault(PyObject *unicode)

使用 Py_FileSystemDefaultEncodeErrors 错误处理程序将 Unicode 对象编码为 Py_FileSystemDefaultEncoding，并返回 bytes。请注意，生成的 bytes 对象可能包含空字节。

如果未设置 Py_FileSystemDefaultEncoding，则回退到语言环境编码。

Py_FileSystemDefaultEncoding 在启动时从语言环境编码初始化，以后无法修改。如果需要将字符串编码为当前语言环境编码，请使用 PyUnicode_EncodeLocale()。

也可以看看

Py_EncodeLocale() 函数。

3.2 版中的新功能。

3.6 版更改：使用 Py_FileSystemDefaultEncodeErrors 错误处理程序。

wchar_t 支持

wchar_t 对支持它的平台的支持：

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

从给定大小的 wchar_t 缓冲区 w 创建一个 Unicode 对象。将 -1 作为 size 传递表示函数必须自己计算长度，使用 wcslen。失败时返回 NULL。

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

将 Unicode 对象内容复制到 wchar_t 缓冲区 w。最多复制 size wchar_t 个字符（不包括可能的尾随空终止字符）。如果出错，返回复制的 wchar_t 个字符或 -1 个字符的数量。请注意，生成的 wchar_t* 字符串可能会或可能不会以空字符结尾。如果应用程序需要，调用者有责任确保 wchar_t* 字符串以空字符结尾。另请注意，wchar_t* 字符串可能包含空字符，这会导致该字符串在与大多数 C 函数一起使用时被截断。

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

将 Unicode 对象转换为宽字符串。输出字符串总是以空字符结尾。如果 size 不是 NULL，则将宽字符数（不包括尾随空终止符）写入 *size。

成功时返回由 PyMem_Alloc() 分配的缓冲区（使用 PyMem_Free() 释放它）。出错时，返回 NULL，*size 未定义并引发 MemoryError。请注意，生成的 wchar_t 字符串可能包含空字符，这会导致该字符串在与大多数 C 函数一起使用时被截断。

3.2 版中的新功能。

内置编解码器

Python 提供了一组用 C 编写的内置编解码器以提高速度。所有这些编解码器都可以通过以下功能直接使用。

以下许多 API 采用编码和错误两个参数，它们与内置的 str() 字符串对象构造函数具有相同的语义。

将 encoding 设置为 NULL 会导致使用默认编码，即 ASCII。文件系统调用应使用 PyUnicode_FSConverter() 对文件名进行编码。这在内部使用变量 Py_FileSystemDefaultEncoding。这个变量应该被视为只读：在某些系统上，它将是一个指向静态字符串的指针，在其他系统上，它会在运行时发生变化（例如当应用程序调用 setlocale 时）。

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

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

通用编解码器

这些是通用编解码器 API：

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

通过解码编码字符串 s 的 size 字节来创建一个 Unicode 对象。 encoding 和 errors 与 str() 内置函数中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

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

编码一个 Unicode 对象并将结果作为 Python 字节对象返回。 encoding 和 errors 与 Unicode encode() 方法中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors)

对给定 size 的 Py_UNICODE 缓冲区 s 进行编码并返回 Python 字节对象。 encoding 和 errors 与 Unicode encode() 方法中的同名参数含义相同。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL。

UTF-8 编解码器

这些是 UTF-8 编解码器 API：

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

通过解码 UTF-8 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

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

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF8()。如果 consumed 不是 NULL，尾随不完整的 UTF-8 字节序列将不会被视为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF8String(PyObject *unicode)

使用 UTF-8 对 Unicode 对象进行编码，并将结果作为 Python 字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

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

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

在出现错误的情况下，返回 NULL 并设置异常并且不存储 size。

这将字符串的 UTF-8 表示缓存在 Unicode 对象中，后续调用将返回指向同一缓冲区的指针。调用者不负责释放缓冲区。

3.3 版中的新功能。

char *PyUnicode_AsUTF8(PyObject *unicode): 作为 PyUnicode_AsUTF8AndSize()，但不存储大小。

3.3 版中的新功能。

PyObject *PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

使用 UTF-8 对给定 size 的 Py_UNICODE 缓冲区 s 进行编码，并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

UTF-32 编解码器

这些是 UTF-32 编解码器 API：

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

从 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 *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF32()。如果 consumed 不是 NULL，则 PyUnicode_DecodeUTF32Stateful() 不会将尾随不完整的 UTF-32 字节序列（例如不能被四整除的字节数）视为一个错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF32String(PyObject *unicode)

以本机字节顺序使用 UTF-32 编码返回 Python 字节字符串。该字符串始终以 BOM 标记开头。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

返回一个 Python 字节对象，其中包含 s 中 Unicode 数据的 UTF-32 编码值。输出按照以下字节顺序写入：

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

如果 byteorder 为 0，则输出字符串将始终以 Unicode BOM 标记 (U+FEFF) 开头。在其他两种模式中，没有预先添加 BOM 标记。

如果未定义 Py_UNICODE_WIDE，则代理对将作为单个代码点输出。

如果编解码器引发异常，则返回 NULL。

UTF-16 编解码器

这些是 UTF-16 编解码器 API：

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

从 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 *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed)

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF16()。如果 consumed 不是 NULL，PyUnicode_DecodeUTF16Stateful() 将不会处理尾随不完整的 UTF-16 字节序列（例如奇数字节或拆分代理对) 作为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsUTF16String(PyObject *unicode)

以本机字节顺序使用 UTF-16 编码返回 Python 字节字符串。该字符串始终以 BOM 标记开头。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder)

返回一个 Python 字节对象，其中包含 s 中 Unicode 数据的 UTF-16 编码值。输出按照以下字节顺序写入：

byteorder == -1: little endian
byteorder == 0:  native byte order (writes a BOM mark)
byteorder == 1:  big endian

如果 byteorder 为 0，则输出字符串将始终以 Unicode BOM 标记 (U+FEFF) 开头。在其他两种模式中，没有预先添加 BOM 标记。

如果定义了 Py_UNICODE_WIDE，则单个 Py_UNICODE 值可能会表示为代理对。如果未定义，则每个 Py_UNICODE 值都被解释为 UCS-2 字符。

如果编解码器引发异常，则返回 NULL。

UTF-7 编解码器

这些是 UTF-7 编解码器 API：

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

通过解码 UTF-7 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

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

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeUTF7()。如果 consumed 不是 NULL，尾随不完整的 UTF-7 base-64 部分将不会被视为错误。这些字节不会被解码，已经解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors)

使用 UTF-7 编码给定大小的 Py_UNICODE 缓冲区并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

如果 base64SetO 非零，“Set O”（没有其他特殊含义的标点符号）将以 base-64 编码。如果 base64WhiteSpace 非零，空格将被编码为 base-64。对于 Python“utf-7”编解码器，两者都设置为零。

Unicode 转义编解码器

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

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

通过解码 Unicode-Escape 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsUnicodeEscapeString(PyObject *unicode)

使用 Unicode-Escape 对 Unicode 对象进行编码，并将结果作为字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

使用 Unicode-Escape 对给定 size 的 Py_UNICODE 缓冲区进行编码并返回一个字节对象。如果编解码器引发异常，则返回 NULL。

原始 Unicode 转义编解码器

这些是“原始 Unicode 转义”编解码器 API：

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

通过解码 Raw-Unicode-Escape 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode)

使用 Raw-Unicode-Escape 对 Unicode 对象进行编码，并将结果作为字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size)

使用 Raw-Unicode-Escape 对给定 size 的 Py_UNICODE 缓冲区进行编码，并返回一个字节对象。如果编解码器引发异常，则返回 NULL。

拉丁 1 编解码器

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

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

通过解码 Latin-1 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsLatin1String(PyObject *unicode)

使用 Latin-1 对 Unicode 对象进行编码，并将结果作为 Python 字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

使用 Latin-1 对给定 size 的 Py_UNICODE 缓冲区进行编码，并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

ASCII 编解码器

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

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

通过解码 ASCII 编码字符串 s 的 size 字节来创建一个 Unicode 对象。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_AsASCIIString(PyObject *unicode)

使用 ASCII 编码 Unicode 对象并将结果作为 Python 字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

使用 ASCII 编码给定 size 的 Py_UNICODE 缓冲区并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

字符映射编解码器

这个编解码器的特殊之处在于它可以用来实现许多不同的编解码器（实际上这是为了获得 encodings 包中包含的大多数标准编解码器所做的）。编解码器使用映射来编码和解码字符。提供的映射对象必须支持__getitem__()映射接口；字典和序列运行良好。

这些是映射编解码器 API：

PyObject *PyUnicode_DecodeCharmap(const char *data, Py_ssize_t size, PyObject *mapping, const char *errors)

通过使用给定的 mapping 对象解码编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

如果 mapping 是 NULL，则将应用 Latin-1 解码。否则 mapping 必须将字节序数（0 到 255 范围内的整数）映射到 Unicode 字符串、整数（然后被解释为 Unicode 序数）或 None。未映射的数据字节——导致 LookupError 以及映射到 None、0xFFFE 或 '\ufffe' 的数据字节被视为未定义的映射并导致错误。

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

使用给定的 mapping 对象对 Unicode 对象进行编码，并将结果作为字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

mapping 对象必须将 Unicode 序数整数映射到字节对象，范围为 0 到 255 或 None 的整数。未映射的字符序数（导致 LookupError）以及映射到 None 的字符序数被视为“未定义映射”并导致错误。

PyObject *PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

使用给定的 mapping 对象对给定 size 的 Py_UNICODE 缓冲区进行编码，并将结果作为字节对象返回。如果编解码器引发异常，则返回 NULL。

以下编解码器 API 的特殊之处在于将 Unicode 映射到 Unicode。

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

使用给定的 mapping 对象翻译 Unicode 对象并返回结果 Unicode 对象。如果编解码器引发异常，则返回 NULL。

mapping 对象必须将 Unicode 序数整数映射到 Unicode 字符串、整数（然后被解释为 Unicode 序数）或 None（导致字符删除）。未映射的字符序数（导致 LookupError）保持不变并按原样复制。

PyObject *PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors)

通过向其应用字符 mapping 表来转换给定 size 的 Py_UNICODE 缓冲区并返回生成的 Unicode 对象。当编解码器引发异常时返回 NULL。

适用于 Windows 的 MBCS 编解码器

这些是 MBCS 编解码器 API。它们目前仅在 Windows 上可用并使用 Win32 MBCS 转换器来实现转换。请注意，MBCS（或 DBCS）是一类编码，而不仅仅是一种。目标编码由运行编解码器的机器上的用户设置定义。

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

通过解码 MBCS 编码字符串 s 的 size 字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL。

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

如果 consumed 是 NULL，则行为类似于 PyUnicode_DecodeMBCS()。如果 consumed 不是 NULL，则 PyUnicode_DecodeMBCSStateful() 将不会解码尾随前导字节，并且已解码的字节数将存储在 consumed 中。

PyObject *PyUnicode_AsMBCSString(PyObject *unicode)

使用 MBCS 对 Unicode 对象进行编码，并将结果作为 Python 字节对象返回。错误处理是“严格的”。如果编解码器引发异常，则返回 NULL。

PyObject *PyUnicode_EncodeCodePage(int code_page, PyObject *unicode, const char *errors): 使用指定的代码页对 Unicode 对象进行编码并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。使用 CP_ACP 代码页获取 MBCS 编码器。

3.3 版中的新功能。

PyObject *PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors)

使用 MBCS 对给定 size 的 Py_UNICODE 缓冲区进行编码并返回 Python 字节对象。如果编解码器引发异常，则返回 NULL。

方法和插槽

方法和槽函数

以下 API 能够处理输入时的 Unicode 对象和字符串（我们在描述中将它们称为字符串）并适当地返回 Unicode 对象或整数。

如果发生异常，它们都返回 NULL 或 -1。

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

连接两个字符串，给出一个新的 Unicode 字符串。

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

拆分一个字符串，给出一个 Unicode 字符串列表。如果 sep 是 NULL，将在所有空白子串上进行拆分。否则，在给定的分隔符处发生拆分。最多会完成 maxsplit 次分割。如果为负，则不设置限制。结果列表中不包含分隔符。

PyObject *PyUnicode_Splitlines(PyObject *s, int keepend)

在换行符处拆分 Unicode 字符串，返回 Unicode 字符串列表。 CRLF 被认为是一个换行符。如果 keepend 是 0，则结果字符串中不包含换行符。

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

通过向字符串应用字符映射表来翻译字符串并返回结果 Unicode 对象。

映射表必须将 Unicode 序数整数映射到 Unicode 序数整数或 None（导致字符删除）。

映射表只需提供__getitem__()接口；字典和序列运行良好。未映射的字符序数（导致 LookupError）保持不变并按原样复制。

errors 具有编解码器的通常含义。它可能是 NULL 表示使用默认错误处理。

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

使用给定的 separator 连接字符串序列并返回结果 Unicode 字符串。

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

如果 substr 在给定的尾端匹配 str[start:end]，则返回 1（direction == -1 表示进行前缀匹配， direction == 1 后缀匹配），否则为 0。如果发生错误，则返回 -1。

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

使用给定的 direction 返回 str[start:end] 中 substr 的第一个位置（direction == 1 表示做一个前向搜索，direction == -1 向后搜索）。返回值是第一个匹配的索引； -1 的值表示未找到匹配项，-2 表示发生错误并设置了异常。

Py_ssize_t PyUnicode_FindChar(PyObject *str, Py_UCS4 ch, Py_ssize_t start, Py_ssize_t end, int direction): 使用给定的 direction 返回字符 ch 在 str[start:end] 中的第一个位置（direction == 1 表示做向前搜索，direction == -1 向后搜索）。返回值是第一个匹配的索引； -1 的值表示未找到匹配项，-2 表示发生错误并设置了异常。

3.3 版中的新功能。

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

返回 str[start:end] 中 substr 的非重叠出现次数。如果发生错误，则返回 -1。

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

将 str 中 substr 的最多 maxcount 次替换为 replstr，并返回生成的 Unicode 对象。 maxcount == -1 表示替换所有出现。

int PyUnicode_Compare(PyObject *left, PyObject *right)

比较两个字符串并分别返回 -1、0、1 的小于、等于和大于。

此函数在失败时返回 -1，因此应调用 PyErr_Occurred() 来检查错误。

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

比较 unicode 对象 uni 与 string 并返回 -1、0、1 的小于、等于和分别大于。最好只传递 ASCII 编码的字符串，但如果输入字符串包含非 ASCII 字符，该函数会将输入字符串解释为 ISO-8859-1。

此函数不会引发异常。

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

Rich 比较两个 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)

从 format 和 args 返回一个新的字符串对象；这类似于 format % args。

int PyUnicode_Contains(PyObject *container, PyObject *element)

检查 element 是否包含在 container 中，并相应返回 true 或 false。

element 必须强制转换为一个元素的 Unicode 字符串。如果出现错误，则返回 -1。

void PyUnicode_InternInPlace(PyObject **string)

将参数 *string 实习到位。参数必须是指向 Python unicode 字符串对象的指针变量的地址。如果存在与 *string 相同的内部字符串，则将其设置为 *string（减少旧字符串对象的引用计数并增加对象的引用计数）实习字符串对象），否则它会留下 *string 单独并实习它（增加其引用计数）。（澄清：尽管有很多关于引用计数的讨论，但将此函数视为引用计数中立；当且仅当您在调用之前拥有该对象时，您才在调用后拥有该对象。）

PyObject *PyUnicode_InternFromString(const char *v)

PyUnicode_FromString() 和 PyUnicode_InternInPlace() 的组合，返回一个新的 unicode 字符串对象，或者一个新的（“拥有的”）引用到一个更早的 interned 字符串对象具有相同的值。

Unicode 对象和编解码器 — Python 文档

目录

Unicode 对象和编解码器

Unicode 对象

Unicode 类型

Unicode 字符属性

创建和访问 Unicode 字符串

已弃用的 Py_UNICODE API

语言环境编码

文件系统编码

wchar_t 支持

内置编解码器

通用编解码器

UTF-8 编解码器

UTF-32 编解码器

UTF-16 编解码器

UTF-7 编解码器

Unicode 转义编解码器

原始 Unicode 转义编解码器

拉丁 1 编解码器

ASCII 编解码器

字符映射编解码器

适用于 Windows 的 MBCS 编解码器

方法和插槽

方法和槽函数