Unicode 对象和编解码器

Unicode Objects

Unicode Type

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

Py_UNICODE
- 这种类型表示存储类型，Python 内部将其用作保存 Unicode 序号的基础。 Python 的默认构建对Py_UNICODE使用 16 位类型，并将 Unicode 值在内部存储为 UCS2.也可以构建 Python 的 UCS4 版本(Python 的 UCS4 构建随附最新的 Linux 发行版)。然后，这些构建将 32 位类型用于Py_UNICODE，并将 Unicode 数据内部存储为 UCS4.在提供wchar_t并且与所选 Python Unicode 构建版本兼容的平台上，Py_UNICODE是wchar_t的 typedef 别名，以增强本机平台的兼容性。在所有其他平台上，Py_UNICODE是unsigned short(UCS2)或unsigned long(UCS4)的 typedef 别名。

请注意，UCS2 和 UCS4 Python 版本不是二进制兼容的。编写扩展或接口时，请记住这一点。

PyUnicodeObject
- PyObject的此子类型表示 Python Unicode 对象。
PyTypeObject PyUnicode_Type
- PyTypeObject的此实例表示 Python Unicode 类型。暴露给unicode和types.UnicodeType的 Python 代码。

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

int PyUnicode_Check(PyObject ** o *)
- 如果对象* o *是 Unicode 对象或 Unicode 子类型的实例，则返回 true。

在版本 2.2 中更改：接受允许的子类型。

int PyUnicode_CheckExact(PyObject ** o *)
- 如果对象* o *是 Unicode 对象，但不是子类型的实例，则返回 true。

2.2 版中的新Function。

Py_ssize_t PyUnicode_GET_SIZE(PyObject ** o *)
- 返回对象的大小。 * o *必须为PyUnicodeObject(未选中)。

在版本 2.5 中进行了更改：此函数返回了int类型。这可能需要更改您的代码以正确支持 64 位系统。

Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject ** o *)
- 返回对象内部缓冲区的大小(以字节为单位)。 * o *必须为PyUnicodeObject(未选中)。

在版本 2.5 中进行了更改：此函数返回了int类型。这可能需要更改您的代码以正确支持 64 位系统。

Py_UNICODE * PyUnicode_AS_UNICODE(PyObject ** o *)
- 返回一个指向对象内部Py_UNICODE缓冲区的指针。 * o *必须是PyUnicodeObject(未选中)。
const char * PyUnicode_AS_DATA(PyObject ** o *)
- 返回一个指向对象内部缓冲区的指针。 * o *必须为PyUnicodeObject(未选中)。
int PyUnicode_ClearFreeList()
- 清除空闲列表。返回释放的项目总数。

2.6 版的新Function。

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。

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

Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE * ch *)
- 返回转换成小写字母的字符* ch *。
Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE * ch *)
- 返回转换成大写字母的字符* ch *。
Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE * ch *)
- 返回转换为标题的* ch *字符。
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。此宏不会引发异常。

Plain Py_UNICODE

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

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

从给定大小的 Py_UNICODE 缓冲区* u *创建一个 Unicode 对象。 * u 可能是 NULL ，导致内容未定义。填写所需数据是用户的责任。缓冲区被复制到新对象中。如果缓冲区不是 NULL ，则返回值可能是共享对象。因此，仅当 u 为 NULL *时才允许修改所得的 Unicode 对象。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

从 char 缓冲区* u *创建一个 Unicode 对象。字节将被解释为 UTF-8 编码。 * u 也可能是 NULL ，这将导致内容未定义。填写所需数据是用户的责任。缓冲区被复制到新对象中。如果缓冲区不是 NULL ，则返回值可能是共享对象。因此，仅当 u 为 NULL *时才允许修改所得的 Unicode 对象。

2.6 版的新Function。

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

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

2.6 版的新Function。

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

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

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

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

2.6 版的新Function。

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

与PyUnicode_FromFormat()相同，除了它只接受两个参数。

2.6 版的新Function。

Py_UNICODE * PyUnicode_AsUnicode(PyObject ** unicode *)
- 返回指向 Unicode 对象内部Py_UNICODE缓冲区的只读指针，如果* unicode 不是 Unicode 对象，则返回 NULL *。请注意，结果Py_UNICODE*字符串可能包含嵌入的空字符，当在大多数 C 函数中使用该字符串时，该字符串会被截断。
Py_ssize_t PyUnicode_GetSize(PyObject ** unicode *)
- 返回 Unicode 对象的长度。

在版本 2.5 中进行了更改：此函数返回了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_FromEncodedObject(PyObject *obj ，const char encoding *，const char ** errors *)
- 返回值：新参考.

将编码对象* obj *强制转换为 Unicode 对象，并以增加的引用计数返回引用。

字符串和其他与 char 缓冲区兼容的对象根据给定的编码并使用错误定义的错误处理进行解码。两者都可以为* NULL *，以使接口使用默认值(有关详细信息，请参见下一节)。

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

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

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

PyUnicode_FromEncodedObject(obj, NULL, "strict")的快捷方式，在需要强制转换为 Unicode 时，将在整个解释器中使用。

如果平台支持wchar_t并提供头文件 wchar.h，则 Python 可以使用以下函数直接与该类型接口。如果 Python 自己的Py_UNICODE类型与系统的wchar_t相同，则会优化支持。

wchar_t Support

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

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

从给定* size 的wchar_t缓冲区 w 创建一个 Unicode 对象。失败时返回 NULL *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode ，wchar_t w *，Py_ssize_t * size *)
- 将 Unicode 对象的内容复制到wchar_t缓冲区* w 。最多复制 size * wchar_t个字符(不包括可能在结尾的 0 终止字符)。返回已复制的wchar_t个字符的数量，如果出错则返回-1的数量。请注意，结果wchar_t字符串可能会或可能不会以 0 结尾。如果应用程序要求wchar_t字符串以 0 结尾，则调用方有责任。另外，请注意wchar_t*字符串可能包含空字符，当与大多数 C 函数一起使用时，这将导致该字符串被截断。

在版本 2.5 中更改：此函数返回int类型，并为_size *使用int类型。这可能需要更改您的代码以正确支持 64 位系统。

Built-in Codecs

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

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

将编码设置为* NULL *会导致使用默认编码，即 ASCII。文件系统调用应使用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 与unicode()内置函数中具有相同名称的参数具有相同的含义。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

对 Unicode 对象进行编码，然后将结果作为 Python 字符串对象返回。 * encoding 和 errors 与 Unicode encode()方法中具有相同名称的参数具有相同的含义。使用 Python 编解码器注册表查找要使用的编解码器。如果编解码器引发异常，则返回 NULL *。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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 *中。

2.4 版的新Function。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsUTF8String(PyObject ** unicode *)
- 返回值：新参考.

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

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。

在狭窄的构建中，BMP 外部的代码点将被解码为代理对。

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

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

2.6 版的新Function。

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 *中。

2.6 版的新Function。

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 *。

2.6 版的新Function。

PyObject * PyUnicode_AsUTF32String(PyObject ** unicode *)
- 以本地字节 Sequences 使用 UTF-32 编码返回 Python 字符串。该字符串始终以 BOM 表标记开头。错误处理是“严格的”。如果编解码器引发异常，则返回* NULL *。

2.6 版的新Function。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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 *中。

2.4 版的新Function。

在版本 2.5 中进行了更改：此函数将_类型用于* size 和int *类型用于 consumed *。这可能需要更改您的代码以正确支持 64 位系统。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsUTF16String(PyObject ** unicode *)
- 返回值：新参考.

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

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”编解码器，两者都设置为零。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsUnicodeEscapeString(PyObject ** unicode *)
- 返回值：新参考.

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

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsRawUnicodeEscapeString(PyObject ** unicode *)
- 返回值：新参考.

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

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsLatin1String(PyObject ** unicode *)
- 返回值：新参考.

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

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsASCIIString(PyObject ** unicode *)
- 返回值：新参考.

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

字符 Map 编解码器

该编解码器的特殊之处在于，它可用于实现许多不同的编解码器(事实上，这样做是为了获得encodings软件包中包含的大多数标准编解码器)。编解码器使用 Map 来编码和解码字符。

解码 Map 必须将单个字符串字符 Map 为单个 Unicode 字符，整数(然后将其解释为 Unicode 序数)或None(表示“未定义的 Map”并导致错误)。

编码 Map 必须将单个 Unicode 字符 Map 为单个字符串字符，整数(然后将其解释为 Latin-1 序数)或None(表示“未定义的 Map”并导致错误)。

提供的 Map 对象必须仅支持__getitem_Map 接口。

如果字符查找失败并出现 LookupError，则按原样复制字符，这意味着其序数值将被解释为 Unicode 或 Latin-1 序数表示形式。因此，Map 仅需要包含将字符 Map 到不同代码点的那些 Map。

这些是 Map 编解码器 API：

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

pass使用给定的* mapping 对象解码 s 个编码字符串的 size 个字节来创建 Unicode 对象。如果编解码器引发异常，则返回 NULL 。如果 mapping 为 NULL *，则将执行 latin-1 解码。否则它可以是字典 Map 字节或 unicode 字符串，它被视为查找表。大于字符串长度和 U FFFE“字符”的字节值被视为“未定义 Map”。

在版本 2.4 中更改：允许将 unicode 字符串作为 Map 参数。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

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

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

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

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

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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 *。

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_DecodeMBCSStateful(const char **s ，int * size ，const char errors *，int ** consumed *)
- 如果* consumed 为 NULL ，则表现为PyUnicode_DecodeMBCS()。如果 consumed 不是 NULL ，则PyUnicode_DecodeMBCSStateful()将不会解码尾随前导字节，并且已解码的字节数将存储在 consumed *中。

2.5 版的新Function。

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

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

在版本 2.5 中进行了更改：此Function为* size *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_AsMBCSString(PyObject ** unicode *)
- 返回值：新参考.

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

方法和插槽

方法和插槽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 *个分割完成。如果为负，则未设置限制。分隔符不包括在结果列表中。

在版本 2.5 中更改：此函数对* maxsplit *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

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。

在版本 2.5 中进行了更改：此函数将int类型用于* start 和 end *。这可能需要更改您的代码以正确支持 64 位系统。

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的值表示发生了错误并且已设置异常。

在版本 2.5 中进行了更改：此函数将int类型用于* start 和 end *。这可能需要更改您的代码以正确支持 64 位系统。

Py_ssize_t PyUnicode_Count(PyObject *str ，PyObject substr *，Py_ssize_t * start *，Py_ssize_t * end *)
- 返回str[start:end]中* substr *的不重叠出现次数。如果发生错误，则返回-1。

在版本 2.5 中进行了更改：此函数返回int类型，并将int类型用于* start 和 end *。这可能需要更改您的代码以正确支持 64 位系统。

PyObject * PyUnicode_Replace(PyObject *str ，PyObject substr *，PyObject ** replstr *，Py_ssize_t * maxcount *)
- 返回值：新参考.

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

在版本 2.5 中更改：此函数对* maxcount *使用了int类型。这可能需要更改您的代码以正确支持 64 位系统。

int PyUnicode_Compare(PyObject 左，PyObject* 右*)
- 比较两个字符串，并分别返回小于，等于和大于-1，0，1。
int PyUnicode_RichCompare(PyObject *left ，PyObject right *，int * op *)
- Rich 比较两个 unicode 字符串并返回以下之一：
NULL万一引发异常
Py_True或Py_False成功进行比较
Py_NotImplemented如果类型组合未知

注意，Py_EQ和Py_NE比较会导致UnicodeWarning，以防将参数__2 转换为 Unicode 失败。

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。

Docs

Docs4dev

Title here

Unicode 对象和编解码器

Unicode Objects

Unicode Type

Unicode 字符属性

Plain Py_UNICODE

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