创建和访问 Unicode 字符串

xhz

要创建 Unicode 对象和访问其基本序列属性，请使用这些 API：

PyObject *[size=1.1em]PyUnicode_New(Py_ssize_t size, Py_UCS4 maxchar)
返回值：新的引用。

创建一个新的 Unicode 对象。 maxchar 应为可放入字符串的实际最大码位。 作为一个近似值，它可被向上舍入到序列 127, 255, 65535, 1114111 中最接近的值。

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

在 3.3 版本加入.

PyObject *[size=1.1em]PyUnicode_FromKindAndData(int kind, const void *buffer, Py_ssize_t size)
返回值：新的引用。

以给定的 kind 创建一个新的 Unicode 对象（可能的值为 PyUnicode_1BYTE_KIND 等，即 PyUnicode_KIND() 所返回的值）。 buffer 必须指向由此分类所给出的，以每字符 1, 2 或 4 字节单位的 size 大小的数组。

如有必要，输入 buffer 将被拷贝并转换为规范表示形式。 例如，如果 buffer 是一个 UCS4 字符串 (PyUnicode_4BYTE_KIND) 且仅由 UCS1 范围内的码位组成，它将被转换为 UCS1 (PyUnicode_1BYTE_KIND)。

在 3.3 版本加入.

PyObject *[size=1.1em]PyUnicode_FromStringAndSize(const char *str, Py_ssize_t size)
返回值：新的引用。 属于 稳定 ABI.

根据字符缓冲区 str 创建一个 Unicode 对象。 字节数据将按 UTF-8 编码格式来解读。 缓冲区会被拷贝到新的对象中。 返回值可以是一个共享对象，即其数据不允许修改。

此函数会因以下情况而引发 SystemError:

• size < 0,
• str 为 NULL 且 size > 0
  
  

在 3.12 版本发生变更: str == NULL 且 size > 0 不再被允许。

PyObject *[size=1.1em]PyUnicode_FromString(const char *str)
返回值：新的引用。 属于 稳定 ABI.

根据 UTF-8 编码的以空值结束的字符缓冲区 str 创建一个 Unicode 对象。

PyObject *[size=1.1em]PyUnicode_FromFormat(const char *format, ...)
返回值：新的引用。 属于 稳定 ABI.

接受一个 C printf() 风格的 format 字符串和可变数量的参数，计算结果 Python Unicode 字符串的大小并返回包含已格式化值的字符串。 可变数量的参数必须均为 C 类型并且必须恰好与 format ASCII 编码字符串中的格式字符相对应。

转换标记符包含两个或更多字符并具有以下组成，且必须遵循此处规定的顺序：

• '%' 字符，用于标记转换符的起始。
• 转换旗标（可选），用于影响某些转换类型的结果。
• 最小字段宽度（可选）。 如果指定为 '*' (星号)，则实际宽度会在下一参数中给出，该参数必须为 int 类型，要转换的对象则放在最小字段宽度和可选精度之后。
• 精度（可选），以在 '.' (点号) 之后加精度值的形式给出。 如果指定为 '*' (星号)，则实际精度会在下一参数中给出，该参数必须为 int 类型，要转换的对象则放在精度之后。
• 长度修饰符（可选）。
• 转换类型。
  
  

转换旗标为：

标志

含意

0

转换将为数字值填充零字符。

-

转换值将靠左对齐（如果同时给出则会覆盖 0 旗标）。

以下整数转换的长度修饰符 (d, i, o, u, x, or 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) 和一个以空值结束的 C 字符数组作为第二个形参（如果第一个形参为 NULL，第二个形参将被使用）。

S

PyObject*

调用 PyObject_Str() 的结果。

R

PyObject*

调用 PyObject_Repr() 的结果。

备注

格式符的宽度单位是字符数而不是字节数。 格式符的精度单位对于 "%s" 和 "%V" (如果 PyObject* 参数为 NULL) 是字节数或 wchar_t 项数 (如果使用了长度修饰符 l)，而对于 "%A", "%U", "%S", "%R" 和 "%V" (如果 PyObject* 参数不为 NULL) 则为字符数。

备注

与 C printf() 不同的是 0 旗标即使在为整数转换 (d, i, u, o, x, or X) 指定精度时也是有效的。

在 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。 在之前版本中它会导致所有剩余格式字符串被原样拷贝到结果字符串，并丢弃任何额外的参数。

PyObject *[size=1.1em]PyUnicode_FromFormatV(const char *format, va_list vargs)
返回值：新的引用。 属于 稳定 ABI.

等同于 PyUnicode_FromFormat() 但它将接受恰好两个参数。

PyObject *[size=1.1em]PyUnicode_FromObject(PyObject *obj)
返回值：新的引用。 属于 稳定 ABI.

如有必要将把一个 Unicode 子类型的实例拷贝为新的真实 Unicode 对象。 如果 obj 已经是一个真实 Unicode 对象（而非子类型），则返回一个新的指向该对象的 strong reference。

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

PyObject *[size=1.1em]PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors)
返回值：新的引用。 属于 稳定 ABI.

将一个已编码的对象 obj 解码为 Unicode 对象。

bytes, bytearray 和其他 字节类对象 将按照给定的 encoding 来解码并使用由 errors 定义的错误处理方式。 两者均可为 NULL 即让接口使用默认值（请参阅 内置编解码器 了解详情）。

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

如有错误该 API 将返回 NULL。 调用方要负责递减指向所返回对象的引用。

Py_ssize_t [size=1.1em]PyUnicode_GetLength(PyObject *unicode)
属于 稳定 ABI 自 3.7 版开始.

返回 Unicode 对象码位的长度。

在 3.3 版本加入.

Py_ssize_t [size=1.1em]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 [size=1.1em]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 [size=1.1em]PyUnicode_WriteChar(PyObject *unicode, Py_ssize_t index, Py_UCS4 character)
属于 稳定 ABI 自 3.7 版开始.

将一个字符写入到字符串。 字符串必须通过 PyUnicode_New() 创建。 由于 Unicode 字符串应当是不可变的，因此该字符串不能被共享，或是被哈希。

该函数将检查 unicode 是否为 Unicode 对象，索引是否未越界，并且对象是否可被安全地修改（即其引用计数为一）。

在 3.3 版本加入.

Py_UCS4 [size=1.1em]PyUnicode_ReadChar(PyObject *unicode, Py_ssize_t index)
属于 稳定 ABI 自 3.7 版开始.

从字符串读取一个字符。 该函数将检查 unicode 是否为 Unicode 对象且索引是否未越界，这不同于 PyUnicode_READ_CHAR()，后者不会执行任何错误检查。

在 3.3 版本加入.

PyObject *[size=1.1em]PyUnicode_Substring(PyObject *unicode, Py_ssize_t start, Py_ssize_t end)
返回值：新的引用。 属于 稳定 ABI 自 3.7 版开始.

返回 unicode 的一个子串，从字符索引 start (包括) 到字符索引 end (不包括)。 不支持负索引号。

在 3.3 版本加入.

Py_UCS4 *[size=1.1em]PyUnicode_AsUCS4(PyObject *unicode, Py_UCS4 *buffer, Py_ssize_t buflen, int copy_null)
属于 稳定 ABI 自 3.7 版开始.

将字符串 unicode 拷贝到一个 UCS4 缓冲区，包括一个空字符，如果设置了 copy_null 的话。 出错时返回 NULL 并设置一个异常（特别是当 buflen 小于 unicode 的长度时，将设置 SystemError 异常）。 成功时返回 buffer。

在 3.3 版本加入.

Py_UCS4 *[size=1.1em]PyUnicode_AsUCS4Copy(PyObject *unicode)
属于 稳定 ABI 自 3.7 版开始.

将字符串 unicode 拷贝到使用 PyMem_Malloc() 分配的新 UCS4 缓冲区。 如果执行失败，将返回 NULL 并设置 MemoryError。 返回的缓冲区将总是会添加一个额外的空码位。

在 3.3 版本加入.