String/Bytes Objects

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

• PyStringObject

  • PyObject的此子类型表示 Python 字符串对象。

• PyTypeObject PyString_Type

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

• int PyString_Check(PyObject ** o *)
  • 如果对象* o *是字符串对象或字符串类型的子类型的实例，则返回 true。

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

• int PyString_CheckExact(PyObject ** o *)
  • 如果对象* o *是字符串对象，但不是字符串类型的子类型的实例，则返回 true。

2.2 版中的新Function。

• 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 中更改：此函数为 len 使用int类型。这可能需要更改您的代码以正确支持 64 位系统。

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

采取 C printf()样式的* format 字符串和可变数量的参数，计算所得 Python 字符串的大小，然后返回带有格式化后的值的字符串。变量参数必须是 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")。
%lld	long long	完全等效于printf("%lld")。
%llu	无符号长久	完全等效于printf("%llu")。
%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")基本等效。

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

在 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 *)

  • 返回 NUL 终止的* string 内容的表示形式。指针指向 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 *)

  • pass输出变量* buffer 和 length 返回以 NUL 终止的对象 obj *内容的表示形式。

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

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

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

• 无效PyString_Concat(PyObject *** string ，PyObject* newpart *)

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

• 无效PyString_ConcatAndDel(PyObject *** string ，PyObject* newpart *)

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

• int _PyString_Resize(PyObject *** string *，Py_ssize_t * newsize *)

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

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

• PyObject * PyString_Format(PyObject *format ，PyObject args *)
  • 返回值：新参考.

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

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

• PyObject * PyString_InternFromString(const char ** v *)
  • 返回值：新参考.

PyString_FromString()和PyString_InternInPlace()的组合，返回已被嵌入的新字符串对象，或者返回对具有相同值的更早被嵌入的字符串对象的新(“拥有”)引用。

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

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

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

• PyObject * PyString_AsDecodedObject(PyObject *str ，const char encoding *，const char ** errors *)
  • 返回值：新参考.

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

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

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

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

• PyObject * PyString_AsEncodedObject(PyObject *str ，const char encoding *，const char ** errors *)
  • 返回值：新参考.

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