字符串/字节对象 — Python 文档

字符串/字节对象

这些函数在需要字符串参数时会引发 TypeError 并使用非字符串参数调用。

笔记

这些函数在 Python 3.x 中已重命名为 PyBytes_*。 除非另有说明，3.x 中可用的 PyBytes 函数将别名为其 PyString_* 等效项以帮助移植。

type PyStringObject

PyObject 的这个子类型表示一个 Python 字符串对象。

PyTypeObject PyString_Type

PyTypeObject的这个实例代表Python字符串类型； 它与 Python 层中的 str 和 types.StringType 是同一个对象。 .

int PyString_Check(PyObject *o)

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

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

int PyString_CheckExact(PyObject *o)

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

2.2 版中的新功能。

PyObject *PyString_FromString(const char *v)

返回一个新的字符串对象，其中包含字符串 v 的副本作为成功时的值，失败时返回 NULL。 参数v不能是NULL； 它不会被检查。

PyObject *PyString_FromStringAndSize(const char *v, Py_ssize_t len)

成功返回一个新的字符串对象，其中包含字符串 v 的副本作为值和长度 len，失败时返回 NULL。 如果 v 是 NULL，则字符串的内容未初始化。

2.5 版更改： 此函数使用 int 类型用于 len。 这可能需要更改您的代码才能正确支持 64 位系统。

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

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

格式字符	类型	评论
%%	不适用	The literal % character.
%c	整数	单个字符，表示为 C int。
%d	整数	完全等同于 printf("%d")。
%u	无符号整数	完全等同于 printf("%u")。
%ld	长	完全等同于 printf("%ld")。
%lu	无符号长	完全等同于 printf("%lu")。
%lld	长长的	完全等同于 printf("%lld")。
%llu	无符号长长	完全等同于 printf("%llu")。
%zd	py_ssize_t	完全等同于 printf("%zd")。
%zu	尺寸_t	完全等同于 printf("%zu")。
%i	整数	完全等同于 printf("%i")。
%x	整数	完全等同于 printf("%x")。
%s	字符*	以空字符结尾的 C 字符数组。
%p	空白*	C 指针的十六进制表示。 大部分等同于 printf("%p")，除了它保证以文字 0x 开头，而不管平台的 printf 产生什么。

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

笔记

“%lld” 和 “%llu” 格式说明符仅在定义了 HAVE_LONG_LONG 时才可用。

2.7 版更改： 添加了对 “%lld” 和 “%llu” 的支持。

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

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

Py_ssize_t PyString_Size(PyObject *string)

返回字符串对象 string 中字符串的长度。

2.5 版更改： 此函数返回 int 类型。 这可能需要更改您的代码才能正确支持 64 位系统。

Py_ssize_t PyString_GET_SIZE(PyObject *string)

PyString_Size() 的宏形式，但没有错误检查。

2.5 版更改： 该宏返回 int 类型。 这可能需要更改您的代码才能正确支持 64 位系统。

char *PyString_AsString(PyObject *string)

返回 string 内容的以 NUL 结尾的表示形式。 指针指的是 string 的内部缓冲区，而不是副本。 不得以任何方式修改数据，除非字符串是使用 PyString_FromStringAndSize(NULL, size) 创建的。 它不能被解除分配。 如果 string 是 Unicode 对象，则此函数计算 string 的默认编码并对其进行操作。 如果 string 根本不是字符串对象，则 PyString_AsString() 返回 NULL 并引发 TypeError。

char *PyString_AS_STRING(PyObject *string)

PyString_AsString() 的宏形式，但没有错误检查。 仅支持字符串对象； 不应传递任何 Unicode 对象。

int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

通过输出变量 buffer 和 length 返回对象 obj 内容的以 NUL 结尾的表示。

该函数接受字符串和 Unicode 对象作为输入。 对于 Unicode 对象，它返回对象的默认编码版本。 如果 length 是 NULL，则结果缓冲区可能不包含 NUL 字符； 如果是，则函数返回 -1 并引发 TypeError。

缓冲区指的是 obj 的内部字符串缓冲区，而不是副本。 不得以任何方式修改数据，除非字符串是使用 PyString_FromStringAndSize(NULL, size) 创建的。 它不能被解除分配。 如果 string 是 Unicode 对象，则此函数计算 string 的默认编码并对其进行操作。 如果 string 根本不是字符串对象，则 PyString_AsStringAndSize() 返回 -1 并引发 TypeError。

2.5 版更改：此函数使用 int * 类型作为 length。 这可能需要更改您的代码才能正确支持 64 位系统。

void PyString_Concat(PyObject **string, PyObject *newpart)

在 *string 中创建一个新的字符串对象，其中包含附加到 string 的 newpart 的内容； 调用者将拥有新的引用。 对 string 旧值的引用将被盗。 如果无法创建新字符串，则仍会丢弃对 string 的旧引用，并将 *string 的值设置为 NULL； 将设置适当的例外。

void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)

在 *string 中创建一个新的字符串对象，其中包含附加到 string 的 newpart 的内容。 此版本减少了 newpart 的引用计数。

int _PyString_Resize(PyObject **string, Py_ssize_t newsize)

一种调整字符串对象大小的方法，即使它是“不可变的”。 仅使用它来构建一个全新的字符串对象； 如果在代码的其他部分可能已经知道该字符串，请不要使用它。 如果输入字符串对象上的引用计数不是 1，则调用此函数是错误的。 将现有字符串对象的地址作为左值（可以写入）和所需的新大小传递。 成功时， *string 保存调整大小的字符串对象并返回 0； *string 中的地址可能与其输入值不同。 如果重新分配失败，则在 *string 处的原始字符串对象被释放，*string 设置为 NULL，设置内存异常，以及 -1 返回。

2.5 版更改： 该函数使用 int 类型为 newsize。 这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyString_Format(PyObject *format, PyObject *args)

从 format 和 args 返回一个新的字符串对象。 类似于 format % args。 args 参数必须是元组或字典。

void PyString_InternInPlace(PyObject **string)

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

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。

PyObject *PyString_InternFromString(const char *v)

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

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。

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

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

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。

2.5 版更改： 此函数使用 int 类型作为 大小。 这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)

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

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。

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

通过将给定大小的 char 缓冲区传递给为 encoding 注册的编解码器进行编码，并返回一个 Python 对象。 encoding 和 errors 与字符串 encode() 方法中的同名参数含义相同。 使用 Python 编解码器注册表查找要使用的编解码器。 如果编解码器引发异常，则返回 NULL。

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。

2.5 版更改： 此函数使用 int 类型作为 大小。 这可能需要更改您的代码才能正确支持 64 位系统。

PyObject *PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)

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

笔记

此函数在 3.x 中不可用，并且没有 PyBytes 别名。