Unicode 对象和编解码器

Unicode Objects

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

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

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

“规范” Unicode 对象是由不提倡使用的 Unicode API 创建的所有对象。他们使用实现所允许的最有效的表示形式。
“旧版” Unicode 对象是pass其中一个已弃用的 API(通常为PyUnicode_FromUnicode())创建的，仅带有Py_UNICODE*表示形式；您必须先在它们上调用PyUnicode_READY()，然后再调用其他 API。

Unicode Type

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

Py_UCS4
Py_UCS2
Py_UCS1
- 这些类型是无符号整数类型的 typedef，它们的宽度足以包含 32 位，16 位和 8 位字符。处理单个 Unicode 字符时，请使用Py_UCS4。

版本 3.3 中的新Function。

Py_UNICODE
- 这是wchar_t的 typedef，取决于平台，它是 16 位类型还是 32 位类型。

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

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

版本 3.3 中的新Function。

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 中的新Function。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject ** o *)
- 以代码点形式返回 Unicode 字符串的长度。 * o *必须是“规范”表示形式的 Unicode 对象(未选中)。

版本 3.3 中的新Function。

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 中的新Function。

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

版本 3.3 中的新Function。

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

版本 3.3 中的新Function。

无效* PyUnicode_DATA(PyObject ** o *)
- 返回指向原始 Unicode 缓冲区的 void 指针。 * o *必须是“规范”表示形式的 Unicode 对象(未选中)。

版本 3.3 中的新Function。

无效PyUnicode_WRITE(整数类型，无效**数据*，Py_ssize_t 索引，Py_UCS4 值)
- 写入规范表示* data (passPyUnicode_DATA()获得)。该宏不执行任何完整性检查，并且打算在循环中使用。调用者应缓存从其他宏调用获取的 kind 值和 data *指针。 * index 是字符串中的索引(从 0 开始)， value *是应该写入该位置的新代码点值。

版本 3.3 中的新Function。

Py_UCS4 PyUnicode_READ(int 类型，void *数据，Py_ssize_t * index *)
- 从规范表示形式* data *读取代码点(passPyUnicode_DATA()获得)。不执行检查或准备呼叫。

版本 3.3 中的新Function。

Py_UCS4 PyUnicode_READ_CHAR(PyObject ** o *，Py_ssize_t * index *)
- 从 Unicode 对象* o *中读取字符，该对象必须采用“规范”表示形式。如果您进行多次连续读取，则效率不如PyUnicode_READ()。

版本 3.3 中的新Function。

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

版本 3.3 中的新Function。

int PyUnicode_ClearFreeList()
- 清除空闲列表。返回释放的项目总数。
Py_ssize_t PyUnicode_GET_SIZE(PyObject ** o *)
- 返回已弃用的Py_UNICODE表示形式的大小，以代码单位(包括代理对为 2 个单位)。 * o *必须是 Unicode 对象(未选中)。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：旧式 Unicode API 的一部分，请迁移到使用PyUnicode_GET_LENGTH()。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject ** o *)
- 返回不赞成使用的Py_UNICODE表示形式的大小(以字节为单位)。 * o *必须是 Unicode 对象(未选中)。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：旧式 Unicode API 的一部分，请迁移到使用PyUnicode_GET_LENGTH()。

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并且设置了异常)。try移植代码以使用新的PyUnicode_nBYTE_DATA()宏或使用PyUnicode_WRITE()或PyUnicode_READ()。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：作为旧版 Unicode API 的一部分，请迁移到使用PyUnicode_nBYTE_DATA()系列宏。

Unicode 字符属性

Unicode 提供许多不同的字符属性。pass这些宏可以使用最常用的宏，这些宏根据 Python 配置 Map 到 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 *)
- 返回1或0，具体取决于* ch *是标题字符。
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 开始不推荐使用：此函数使用简单的大小写 Map。

Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE * ch *)
- 返回转换成大写字母的字符* ch *。

从版本 3.3 开始不推荐使用：此函数使用简单的大小写 Map。

Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE * ch *)
- 返回转换为标题的* ch *字符。

从版本 3.3 开始不推荐使用：此函数使用简单的大小写 Map。

int Py_UNICODE_TODECIMAL(Py_UNICODE * ch *)
- 返回转换为十进制正整数的字符* ch *。如果无法返回-1。此宏不会引发异常。
int Py_UNICODE_TODIGIT(Py_UNICODE * ch *)
- 返回转换为一位整数的字符* ch *。如果无法返回-1。此宏不会引发异常。
双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(高，低)
- 连接两个代理字符并返回一个 Py_UCS4 值。高和低分别是代理对中的前导和尾随代理。

创建和访问 Unicode 字符串

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

PyObject * PyUnicode_New(Py_ssize_t * size *，Py_UCS4 * maxchar *)
- 返回值：新参考.

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

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

版本 3.3 中的新Function。

PyObject * PyUnicode_FromKindAndData(int 种类，const void ** buffer *，Py_ssize_t * size *)
- 返回值：新参考.

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

版本 3.3 中的新Function。

PyObject * PyUnicode_FromStringAndSize(const char ** u *，Py_ssize_t * size *)
- 返回值：新参考.

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

如果* u *为NULL，则此函数的行为类似于PyUnicode_FromUnicode()，缓冲区设置为NULL。不推荐使用此用法，而推荐使用PyUnicode_New()。

PyObject * PyUnicode_FromString(const char ** u *)
- 返回值：新参考.

从 UTF-8 编码的以 null 终止的 char 缓冲区* u *创建 Unicode 对象。

PyObject * PyUnicode_FromFormat(const char ** format *，...)
- 返回值：新参考.

使用 C printf()样式的* format 字符串和可变数量的参数，计算所得 Python Unicode 字符串的大小，并返回带有格式化后的值的字符串。变量参数必须是 C 类型，并且必须与 format * ASCII 编码字符串中的格式字符完全对应。允许使用以下格式字符：

Format Characters	Type	Comment
`%%`	n/a	Literals％字符。
`%c`	int	单个字符，表示为 C int。
`%d`	int	等效于`printf("%d")`。 [1]
`%u`	unsigned int	等效于`printf("%u")`。 [1]
`%ld`	long	等效于`printf("%ld")`。 [1]
`%li`	long	等效于`printf("%li")`。 [1]
`%lu`	unsigned long	等效于`printf("%lu")`。 [1]
`%lld`	long long	等效于`printf("%lld")`。 [1]
`%lli`	long long	等效于`printf("%lli")`。 [1]
`%llu`	无符号长久	等效于`printf("%llu")`。 [1]
`%zd`	Py_ssize_t	等效于`printf("%zd")`。 [1]
`%zi`	Py_ssize_t	等效于`printf("%zi")`。 [1]
`%zu`	size_t	等效于`printf("%zu")`。 [1]
`%i`	int	等效于`printf("%i")`。 [1]
`%x`	int	等效于`printf("%x")`。 [1]
`%s`	const char*	空终止的 C 字符数组。
`%p`	const void*	C 指针的十六进制表示。除平台`printf`产生什么结果外，它保证以立即数`0x`开头，因此与`printf("%p")`基本等效。
`%A`	PyObject*	调用ascii()的结果。
`%U`	PyObject*	Unicode 对象。
`%V`	PyObject ，const char	一个 Unicode 对象(可能是`NULL`)和一个以空终止的 C 字符数组作为第二个参数(如果第一个参数是`NULL`，则将使用该数组)。
`%S`	PyObject*	调用PyObject_Str()的结果。
`%R`	PyObject*	调用PyObject_Repr()的结果。

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

Note

宽度格式器单位是字符数，而不是字节数。精度格式器单位是"%s"和"%V"的字节数(如果PyObject*参数是NULL)，以及"%A"，"%U"，"%S"，"%R"和"%V"的字符数(如果PyObject*参数不是NULL)。

1 (1,2,3,4,5,6,7,8,9,10,11,12,13)
- 对于整数说明符(d，u，ld，li，lu，lld，lli，llu，zd，zi，zu，i，x)：即使给出了精度，0 转换标志也有效。

在版本 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 并使用 errors *定义的错误处理进行解码。两者都可以NULL，以使接口使用默认值(有关详细信息，请参见Built-in Codecs)。

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

如果发生错误，API 将返回NULL。调用者负责解密返回的对象。

Py_ssize_t PyUnicode_GetLength(PyObject ** unicode *)
- 以代码点形式返回 Unicode 对象的长度。

版本 3.3 中的新Function。

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 中的新Function。

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并引发错误异常。

版本 3.3 中的新Function。

int PyUnicode_WriteChar(PyObject ** unicode *，Py_ssize_t * index *，Py_UCS4 * character *)
- 将字符写入字符串。该字符串必须已passPyUnicode_New()创建。由于 Unicode 字符串应该是不可变的，因此该字符串不得共享或已被哈希处理。

此函数检查* unicode *是否为 Unicode 对象，索引是否未超出范围以及是否可以安全地修改该对象(即其引用计数为 1)。

版本 3.3 中的新Function。

Py_UCS4 PyUnicode_ReadChar(PyObject ** unicode *，Py_ssize_t * index *)
- 从字符串中读取一个字符。与宏版本PyUnicode_READ_CHAR()相比，此函数检查* unicode *是 Unicode 对象，并且索引是否未超出范围。

版本 3.3 中的新Function。

PyObject * PyUnicode_Substring(PyObject ** str *，Py_ssize_t * start *，Py_ssize_t * end *)
- 返回值：新参考.

从字符索引* start (包括)返回字符索引 end (不包括)，返回 str *的子字符串。不支持负索引。

版本 3.3 中的新Function。

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

版本 3.3 中的新Function。

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

版本 3.3 中的新Function。

不推荐使用的 Py_UNICODE API

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除。

这些 API 函数已在 PEP 393的实现中弃用。扩展模块可以 continue 使用它们，因为它们不会在 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。

从版本 3.3 开始不推荐使用，将在版本 3.10 中删除。

PyObject * PyUnicode_TransformDecimalToASCII(Py_UNICODE ** s *，Py_ssize_t * size *)
- 返回值：新参考.

pass将给定* 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 中的新Function。

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

3.2 版中的新Function。

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

Py_ssize_t PyUnicode_GetSize(PyObject ** unicode *)
- 返回已弃用的Py_UNICODE表示形式的大小，以代码单位(包括代理对为 2 个单位)。

请迁移到使用PyUnicode_GetLength()。

PyObject * PyUnicode_FromObject(PyObject ** obj *)
- 返回值：新参考.

如有必要，将 Unicode 子类型的实例复制到新的真实 Unicode 对象。如果* obj *已经是一个 true 的 Unicode 对象(不是子类型)，则以增加的引用计数返回引用。

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

Locale Encoding

当前的语言环境编码可用于解码来自 os 的文本。

PyObject * PyUnicode_DecodeLocaleAndSize(const char **str ，Py_ssize_t * len ，const char errors *)
- 返回值：新参考.

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

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

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

See also

Py_DecodeLocale()Function。

版本 3.3 中的新Function。

在 3.7 版中进行了更改：该Function现在还为surrogateescape错误处理程序使用了当前的语言环境编码，但 Android 除外。以前，Py_DecodeLocale()用于surrogateescape，而当前语言环境编码用于strict。

PyObject * PyUnicode_DecodeLocale(const char *str ，const char errors *)
- 返回值：新参考.

与PyUnicode_DecodeLocaleAndSize()类似，但是使用strlen()计算字符串长度。

版本 3.3 中的新Function。

PyObject * PyUnicode_EncodeLocale(PyObject *unicode ，const char errors *)
- 返回值：新参考.

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

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

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

See also

Py_EncodeLocale()Function。

版本 3.3 中的新Function。

在 3.7 版中进行了更改：该Function现在还为surrogateescape错误处理程序使用了当前的语言环境编码，但 Android 除外。以前，Py_EncodeLocale()用于surrogateescape，而当前语言环境编码用于strict。

文件系统编码

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

int PyUnicode_FSConverter(PyObject * * obj *，void * 结果)
- ParseTuple 转换器：将str对象(直接获得或passos.PathLike接口获得)编码为使用PyUnicode_EncodeFSDefault()的bytes； bytes对象按原样输出。 * result *必须是PyBytesObject*，不再使用时必须释放它。

3.1 版中的新Function。

在版本 3.6 中更改：接受path-like object。

要将参数名称解析过程中的文件名解码为str，应使用"O&"转换器，并将PyUnicode_FSDecoder()作为转换函数：

int PyUnicode_FSDecoder(PyObject * * obj *，void * 结果)
- ParseTuple 转换器：将bytes对象(passos.PathLike接口直接或间接获得)解码为使用PyUnicode_DecodeFSDefaultAndSize()到str； str对象按原样输出。 * result *必须是PyUnicodeObject*，不再使用时必须释放它。

3.2 版中的新Function。

在版本 3.6 中更改：接受path-like object。

PyObject * PyUnicode_DecodeFSDefaultAndSize(const char ** s *，Py_ssize_t * size *)
- 返回值：新参考.

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

如果未设置Py_FileSystemDefaultEncoding，则回退到区域设置编码。

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

See also

Py_DecodeLocale()Function。

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

PyObject * PyUnicode_DecodeFSDefault(const char ** s *)
- 返回值：新参考.

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

如果未设置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()。

See also

Py_EncodeLocale()Function。

3.2 版中的新Function。

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

wchar_t Support

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

PyObject * PyUnicode_FromWideChar(const wchar_t ** w *，Py_ssize_t * size *)
- 返回值：新参考.

从给定* 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 。请注意，生成的wchar_t字符串可能包含空字符，这将导致该字符串在与大多数 C 函数一起使用时被截断。如果 size *为NULL且wchar_t*字符串包含空字符，则会引发ValueError。

成功返回PyMem_Alloc()分配的缓冲区(使用PyMem_Free()释放缓冲区)。错误时，返回NULL且** size *未定义。如果内存分配失败，则引发MemoryError。

3.2 版中的新Function。

在 3.7 版中进行了更改：如果* size *为NULL并且wchar_t*字符串包含空字符，则引发ValueError。

Built-in Codecs

Python 提供了一组内置的编解码器，这些编解码器使用 C 语言编写以提高速度。所有这些编解码器均可pass以下Function直接使用。

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

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

错误处理由错误设置，错误也可以设置为NULL，以使用为编解码器定义的默认处理。所有内置编解码器的默认错误处理为“严格”(引发ValueError)。

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

Generic Codecs

这些是通用编解码器 API：

PyObject * PyUnicode_Decode(const char **s ，Py_ssize_t * size ，const char encoding *，const char ** errors *)
- 返回值：新参考.

pass解码编码字符串* 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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsEncodedString()。

UTF-8 Codecs

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

PyObject * PyUnicode_DecodeUTF8(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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。

const char * PyUnicode_AsUTF8AndSize(PyObject *unicode ，Py_ssize_t size *)
- 返回一个指向 Unicode 对象的 UTF-8 编码的指针，并将编码表示的大小(以字节为单位)存储在* size *中。 * size 参数可以是NULL;在这种情况下，将不会存储任何尺寸。无论是否还有其他空代码点，返回的缓冲区总会附加一个额外的空字节(不包含在 size *中)。

如果发生错误，则返回NULL并设置一个 exception，并且不存储* size *。

这会将字符串的 UTF-8 表示形式缓存在 Unicode 对象中，随后的调用将返回一个指向相同缓冲区的指针。调用方不负责取消分配缓冲区。

版本 3.3 中的新Function。

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

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

版本 3.3 中的新Function。

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

PyObject * PyUnicode_EncodeUTF8(const Py_UNICODE **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

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

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsUTF8String()，PyUnicode_AsUTF8AndSize()或PyUnicode_AsEncodedString()。

UTF-32 Codecs

这些是 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，则解码器使用给定的字节 Sequences 开始解码：

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

如果*byteorder为零，并且 Importing 数据的前四个字节是字节 Sequences 标记(BOM)，则解码器将切换到该字节 Sequences，并且 BOM 不会复制到结果 Unicode 字符串中。如果*byteorder是-1或1，则将任何字节 Sequences 标记复制到输出。

完成后，将** byteorder *设置为 Importing 数据末尾的当前字节 Sequences。

如果* byteorder *为NULL，则编解码器以本机 Sequences 模式启动。

如果编解码器引发异常，则返回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 *)
- 返回值：新参考.

以本地字节 Sequences 使用 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 编码值。根据以下字节 Sequences 写入输出：

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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsUTF32String()或PyUnicode_AsEncodedString()。

UTF-16 Codecs

这些是 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，则解码器使用给定的字节 Sequences 开始解码：

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

如果*byteorder为零，并且 Importing 数据的前两个字节是字节 Sequences 标记(BOM)，则解码器将切换到该字节 Sequences，并且 BOM 不会复制到结果 Unicode 字符串中。如果*byteorder是-1或1，则任何字节 Sequences 标记都将被复制到输出中(它将导致\ufeff或\ufffe字符)。

完成后，将** byteorder *设置为 Importing 数据末尾的当前字节 Sequences。

如果* byteorder *为NULL，则编解码器以本机 Sequences 模式启动。

如果编解码器引发异常，则返回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 *)
- 返回值：新参考.

以本地字节 Sequences 使用 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 编码值。根据以下字节 Sequences 写入输出：

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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsUTF16String()或PyUnicode_AsEncodedString()。

UTF-7 Codecs

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

PyObject * PyUnicode_DecodeUTF7(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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 不为零，则将以 base-64 编码“ Set O”(标点没有其他特殊含义)。如果 base64WhiteSpace *不为零，则空格将以 base-64 编码。对于 Python“ utf-7”编解码器，两者都设置为零。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsEncodedString()。

Unicode-Escape Codecs

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

PyObject * PyUnicode_DecodeUnicodeEscape(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsUnicodeEscapeString()。

Raw-Unicode-Escape Codecs

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

PyObject * PyUnicode_DecodeRawUnicodeEscape(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsRawUnicodeEscapeString()或PyUnicode_AsEncodedString()。

Latin-1 Codecs

这些是 Latin-1 编解码器 API：Latin-1 对应于前 256 个 Unicode 序号，只有这些在编解码过程中被编解码器接受。

PyObject * PyUnicode_DecodeLatin1(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsLatin1String()或PyUnicode_AsEncodedString()。

ASCII Codecs

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

PyObject * PyUnicode_DecodeASCII(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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。

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsASCIIString()或PyUnicode_AsEncodedString()。

字符 Map 编解码器

该编解码器的特殊之处在于，它可用于实现许多不同的编解码器(实际上，这是为了获得encodings软件包中包含的大多数标准编解码器所做的事情)。编解码器使用 Map 来编码和解码字符。提供的 Map 对象必须支持getitem()Map 接口；字典和序列运作良好。

这些是 Map 编解码器 API：

PyObject * PyUnicode_DecodeCharmap(const char **data ，Py_ssize_t * size ，PyObject mapping *，const char ** errors *)
- 返回值：新参考.

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

如果* mapping 为NULL，则将应用 Latin-1 解码。其他 mapping *必须将字节序号(0 到 255 范围内的整数)Map 到 Unicode 字符串，整数(然后将其解释为 Unicode 序号)或None。未 Map 的数据字节–导致LookupError的字节以及 Map 到None，0xFFFE或'\ufffe'的字节均被视为未定义的 Map，并导致错误。

PyObject * PyUnicode_AsCharmapString(PyObject *unicode ，PyObject mapping *)
- 返回值：新参考.

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

mapping *对象必须将 Unicode 序数整数 Map 到 bytes 对象，即 0 到 255 或None范围内的整数。未 Map 的字符序号(导致LookupError的字符序号)以及 Map 到None的字符序号均被视为“未定义的 Map”，并导致错误。

PyObject * PyUnicode_EncodeCharmap(const Py_UNICODE **s ，Py_ssize_t * size ，PyObject mapping *，const char ** errors *)
- 返回值：新参考.

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

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsCharmapString()或PyUnicode_AsEncodedString()。

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

PyObject * PyUnicode_Translate(PyObject *unicode ，PyObject mapping *，const char ** errors *)
- 返回值：新参考.

使用给定的* mapping *对象转换 Unicode 对象并返回生成的 Unicode 对象。如果编解码器引发异常，则返回NULL。

mapping *对象必须将 Unicode 序数整数 Map 到 Unicode 字符串，整数(然后将其解释为 Unicode 序数)或None(导致字符删除)。未 Map 的字符序号(导致LookupError的字符序号)保持不变，并按原样复制。

PyObject * PyUnicode_TranslateCharmap(const Py_UNICODE **s ，Py_ssize_t * size ，PyObject mapping *，const char ** errors *)
- 返回值：新参考.

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

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_Translate()。或基于通用编解码器的 API

Windows MBCS 编解码器

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

PyObject * PyUnicode_DecodeMBCS(const char **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

pass解码 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 中的新Function。

PyObject * PyUnicode_EncodeMBCS(const Py_UNICODE **s ，Py_ssize_t * size ，const char errors *)
- 返回值：新参考.

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

从版本 3.3 开始不推荐使用，将在版本 4.0 中删除：老式Py_UNICODE API 的一部分；请迁移到使用PyUnicode_AsMBCSString()，PyUnicode_EncodeCodePage()或PyUnicode_AsEncodedString()。

方法和插槽

方法和插槽Function

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

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

PyObject * PyUnicode_Concat(PyObject 左，PyObject* 右*)
- 返回值：新参考.

Concat 提供了一个新的 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 *)
- pass将字符 Map 表应用于字符串来转换字符串，然后返回生成的 Unicode 对象。

Map 表必须将 Unicode 序数整数 Map 到 Unicode 序数整数或None(导致删除字符)。

Map 表只需要提供getitem()接口；字典和序列运作良好。未 Map 的字符序号(导致LookupError的字符序号)保持不变，并按原样复制。

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

PyObject * PyUnicode_Join(PyObject 分隔符，PyObject* seq *)
- 返回值：新参考.

使用给定的分隔符连接字符串序列，并返回结果 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 返回 substr 在str[start:end]中的第一个位置( 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 中的新Function。

在版本 3.7 中更改：现在将* start 和 end *调整为类似于str[start:end]。

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 *)
- 返回值：新参考.

用* replstr 最多替换 str 中 substr 的 maxcount *次，并返回生成的 Unicode 对象。 * maxcount * == -1表示替换所有匹配项。

int PyUnicode_Compare(PyObject 左，PyObject* 右*)
- 比较两个字符串，并分别返回小于，等于和大于-1，0，1。

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

int PyUnicode_CompareWithASCIIString(PyObject *uni ，const char string *)
- 将 Unicode 对象* uni 与 string *进行比较，并分别返回小于，等于和大于-1，0，1。最好只传递 ASCII 编码的字符串，但是如果包含非 ASCII 字符，该函数会将 Importing 字符串解释为 ISO-8859-1.

此函数不会引发异常。

PyObject * PyUnicode_RichCompare(PyObject 左，PyObject* 右*，整数* 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 容器，PyObject* 元素*)
- 检查* container 中是否包含 element *，并相应返回 true 或 false。

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

无效PyUnicode_InternInPlace(PyObject **字符串)
- 将参数 string 实习到位.参数必须是指向 Python Unicode 字符串对象的指针变量的地址.如果存在一个与 string 相同的内部字符串，则会为其设置 string *(减少旧字符串对象的引用计数并增加该内部字符串对象的引用计数)，否则它将离开单独使用“字符串”并将其实习(增加其引用计数)。 (澄清：即使有很多关于引用计数的讨论，也可以将此函数视为引用计数无关的；只有在调用之前拥有对象，您才在调用之后拥有对象.)
PyObject * PyUnicode_InternFromString(const char ** v *)
- 返回值：新参考.

PyUnicode_FromString()和PyUnicode_InternInPlace()的组合，返回已被嵌入的新 Unicode 字符串对象，或返回对具有相同值的先前被嵌入的字符串对象的新(“拥有”)引用。

首页

Python 中文文档

Unicode 对象和编解码器

Unicode Objects

Unicode Type

Unicode 字符属性

创建和访问 Unicode 字符串

不推荐使用的 Py_UNICODE API

Locale Encoding

文件系统编码

wchar_t Support

Built-in Codecs

Generic Codecs

UTF-8 Codecs

UTF-32 Codecs

UTF-16 Codecs

UTF-7 Codecs

Unicode-Escape Codecs

Raw-Unicode-Escape Codecs

Latin-1 Codecs

ASCII Codecs

字符 Map 编解码器

Windows MBCS 编解码器

方法和插槽

方法和插槽Function