Bytes Objects

当期望使用 byte 参数时，这些函数会引发TypeError，并使用 non-bytes 参数进行调用。

• PyBytesObject

  • PyObject的子类型表示 Python 字节对象。

• PyTypeObject PyBytes_Type

  • PyTypeObject的实例表示 Python 字节类型；它与 Python 层中的bytes是同Pair象。

• int PyBytes_Check(PyObject ** o *)

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

• int PyBytes_CheckExact(PyObject ** o *)

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

• PyObject * PyBytes_FromString(const char ** v *)

  • 返回值：新参考.

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

• PyObject * PyBytes_FromStringAndSize(const char ** v *，Py_ssize_t * len *)
  • 返回值：新参考.

返回一个新的字节对象，成功时返回字符串* v 作为副本，成功时返回字符串 len ，失败则返回NULL。如果 v *为NULL，则字节对象的内容未初始化。

• PyObject * PyBytes_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")。 [1]
%u	unsigned int	等效于printf("%u")。 [1]
%ld	long	等效于printf("%ld")。 [1]
%lu	unsigned long	等效于printf("%lu")。 [1]
%zd	Py_ssize_t	等效于printf("%zd")。 [1]
%zu	size_t	等效于printf("%zu")。 [1]
%i	int	等效于printf("%i")。 [1]
%x	int	等效于printf("%x")。 [1]
%s	const char*	空终止的 C 字符数组。
%p	const void*	C 指针的十六进制表示。除平台printf产生什么结果外，它保证以立即数0x开头，因此与printf("%p")基本等效。

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

• 1 (1,2,3,4,5,6,7,8)

  • 对于整数说明符(d，u，ld，lu，zd，zu，i，x)：即使给出精度，0 转换标志也有效。

• PyObject * PyBytes_FromFormatV(const char ** format *，va_list * vargs *)

  • 返回值：新参考.

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

• PyObject * PyBytes_FromObject(PyObject ** o *)
  • 返回值：新参考.

返回实现缓冲区协议的对象* o *的字节表示形式。

• Py_ssize_t PyBytes_Size(PyObject ** o *)

  • 返回字节对象* o *中字节的长度。

• Py_ssize_t PyBytes_GET_SIZE(PyObject ** o *)

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

• char * PyBytes_AsString(PyObject ** o *)

  • 返回指向* o 内容的指针。指针指向 o 的内部缓冲区，该缓冲区由len(o) + 1个字节组成。缓冲区中的最后一个字节始终为空，而不管是否还有其他空字节。除非以PyBytes_FromStringAndSize(NULL, size)创建对象，否则不得以任何方式修改数据。不能释放它。如果 o *根本不是字节对象，则PyBytes_AsString()返回NULL并引发TypeError。

• char * PyBytes_AS_STRING(PyObject ** string *)

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

• int PyBytes_AsStringAndSize(PyObject *obj ，char * buffer *，Py_ssize_t ** length *)

  • pass输出变量* buffer 和 length 返回对象 obj *的空终止内容。

如果* length *为NULL，则 bytes 对象不能包含嵌入的空字节；如果是，函数将返回-1并引发ValueError。

该缓冲区引用* obj 的内部缓冲区，该缓冲区的末尾包括一个附加的空字节(不计入 length )。除非以PyBytes_FromStringAndSize(NULL, size)创建对象，否则不得以任何方式修改数据。不能释放它。如果 obj *根本不是字节对象，则PyBytes_AsStringAndSize()返回-1并引发TypeError。

在版本 3.5 中进行了更改：以前，在 bytes 对象中遇到嵌入式空字节时，引发了TypeError。

• 无效PyBytes_Concat(PyObject 字节，PyObject newpart *)

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

• 无效PyBytes_ConcatAndDel(PyObject 字节，PyObject newpart *)

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

• int _PyBytes_Resize(PyObject *** bytes *，Py_ssize_t * newsize *)

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