Unicode对象

xhz

Unicode对象和编解码器

自从python3.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对象类型：

type Py_UCS4
type Py_UCS2
type Py_UCS1
属于 稳定 ABI.
这些类型是无符号整数类型的类型定义，其宽度足以分别包含 32 位、16 位和 8 位字符。 当需要处理单个 Unicode 字符时，请使用 Py_UCS4。

在 3.3 版本加入.

type Py_UNICODE
这是 wchar_t 的类型定义，根据平台的不同它可能为 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
属于 稳定 ABI.
这个 PyTypeObject 实例代表 Python Unicode 类型。 它作为 str 公开给 Python 代码。

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

int PyUnicode_Check(PyObject *obj)
如果对象 obj 是 Unicode 对象或 Unicode 子类型的实例则返回真值。 此函数总是会成功执行。

int PyUnicode_CheckExact(PyObject *obj)
如果对象 obj 是一个 Unicode 对象，但不是某个子类型的实例则返回真值。 此函数总是会成功执行。

int PyUnicode_READY(PyObject *unicode)
返回 0。 此 API 仅为向下兼容而保留。

在 3.3 版本加入.

自 3.10 版本弃用: 此 API 从 Python 3.12 起将不做任何事。

Py_ssize_t PyUnicode_GET_LENGTH(PyObject *unicode)
返回以码位点数量表示的 Unicode 字符串长度。 unicode 必须为“规范”表示的 Unicode 对象（不会检查这一点）。

在 3.3 版本加入.

Py_UCS1 *PyUnicode_1BYTE_DATA(PyObject *unicode)
Py_UCS2 *PyUnicode_2BYTE_DATA(PyObject *unicode)
Py_UCS4 *PyUnicode_4BYTE_DATA(PyObject *unicode)
返回一个用于直接字符访问的指向转换为 UCS1、UCS2 或 UCS4 整数类型的规范表示的指针。 如果规范表示具有正确的字符大小，则不执行检查；使用 PyUnicode_KIND() 选择正确的函数。

在 3.3 版本加入.

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

在 3.3 版本加入.

在 3.12 版本发生变更: PyUnicode_WCHAR_KIND 已被移除。

int PyUnicode_KIND(PyObject *unicode)
返回一个 PyUnicode 类型的常量（见上文），指明此see above) that indicate how many bytes per character this Unicode 对象用来存储每个字符所使用的字节数。 unicode 必须为“规范”表示的 Unicode 对象（不会检查这一点）。

在 3.3 版本加入.

void *PyUnicode_DATA(PyObject *unicode)
返回一个指向原始 Unicode 缓冲区的空指针。 unicode 必须为“规范”表示的 Unicode 对象（不会检查这一点）。

在 3.3 版本加入.

void PyUnicode_WRITE(int kind, void *data, Py_ssize_t index, Py_UCS4 value)
写入一个规范表示的 data (如同用 PyUnicode_DATA() 获取)。 此函数不会执行正确性检查，被设计为在循环中使用。 调用者应当如同从其他调用中获取一样缓存 kind 值和 data 指针。 index 是字符串中的索引号 (从 0 开始) 而 value 是应写入该位置的新码位值。

在 3.3 版本加入.

Py_UCS4 PyUnicode_READ(int kind, void *data, Py_ssize_t index)
从规范表示的 data (如同用 PyUnicode_DATA() 获取) 中读取一个码位。 不会执行检查或就绪调用。

在 3.3 版本加入.

Py_UCS4 PyUnicode_READ_CHAR(PyObject *unicode, Py_ssize_t index)
从 Unicode 对象 unicode 读取一个字符，必须为“规范”表示形式。 如果你执行多次连续读取则此函数的效率将低于 PyUnicode_READ()。

在 3.3 版本加入.

Py_UCS4 PyUnicode_MAX_CHAR_VALUE(PyObject *unicode)
返回适合基于 unicode 创建另一个字符串的最大码位点，该参数必须为“规范”表示形式。 这始终是一种近似但比在字符串上执行迭代更高效。

在 3.3 版本加入.

int PyUnicode_IsIdentifier(PyObject *unicode)
属于 稳定 ABI.
如果字符串按照语言定义是合法的标识符则返回 1，参见 标识符和关键字 小节。 否则返回 0。

在 3.9 版本发生变更: 如果字符串尚未就绪则此函数不会再调用 Py_FatalError()。