字节对象
********

这些函数在期望附带一个字节串形参但却附带了一个非字节串形参被调用时会引
发 "TypeError"。

PyBytesObject

   这种 "PyObject" 的子类型表示一个 Python 字节对象。

PyTypeObject PyBytes_Type

   "PyTypeObject" 的实例代表一个 Python 字节类型，在 Python 层面它与
   "bytes" 是相同的对象。

int PyBytes_Check(PyObject *o)

   如果对象 *o* 是一个 bytes 对象或者 bytes 类型的子类型的实例则返回真
   值。 此函数总是会成功执行。

int PyBytes_CheckExact(PyObject *o)

   如果对象 *o* 是一个 bytes 对象但不是 bytes 类型的子类型的实例则返回
   真值。 此函数总是会成功执行。

PyObject* PyBytes_FromString(const char *v)
    *Return value: New reference.*

   成功时返回一个以字符串 *v* 的副本为值的新字节串对象，失败时返回
   "NULL"。 形参 *v* 不可为 "NULL"；它不会被检查。

PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
    *Return value: New reference.*

   成功时返回一个以字符串 *v* 的副本为值且长度为 *len* 的新字节串对象
   ，失败时返回 "NULL"。 如果 *v* 为 "NULL"，则不初始化字节串对象的内
   容。

PyObject* PyBytes_FromFormat(const char *format, ...)
    *Return value: New reference.*

   接受一个 C "printf()" 风格的 *format* 字符串和可变数量的参数，计算
   结果 Python 字节串对象的大小并返回参数值经格式化后的字节串对象。 可
   变数量的参数必须均为 C 类型并且必须恰好与 *format* 字符串中的格式字
   符相对应。 允许使用下列格式字符串:

   +---------------------+-----------------+----------------------------------+
   | 格式字符            | 类型            | 注释                             |
   |=====================|=================|==================================|
   | "%%"                | *不适用*        | 文字%字符。                      |
   +---------------------+-----------------+----------------------------------+
   | "%c"                | int             | 一个字节，被表示为一个 C 语言的  |
   |                     |                 | 整型                             |
   +---------------------+-----------------+----------------------------------+
   | "%d"                | int             | 相当于 "printf("%d")". [1]       |
   +---------------------+-----------------+----------------------------------+
   | "%u"                | unsigned int    | 相当于 "printf("%u")". [1]       |
   +---------------------+-----------------+----------------------------------+
   | "%ld"               | 长整型          | 相当于 "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*     | 以 null 为终止符的 C 字符数组。  |
   +---------------------+-----------------+----------------------------------+
   | "%p"                | const void*     | 一个 C 指针的十六进制表示形式。  |
   |                     |                 | 基本等价于 "printf("%p")" 但它会 |
   |                     |                 | 确 保以字面值 "0x" 开头，不论系  |
   |                     |                 | 统平台上 "printf" 的输出是什么。 |
   +---------------------+-----------------+----------------------------------+

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

   [1] 对于整数说明符（d，u，ld，lu，zd，zu，i，x）：当给出精度时，0
       转换标志是有效的。

PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
    *Return value: New reference.*

   与 "PyBytes_FromFormat()" 完全相同，除了它需要两个参数。

PyObject* PyBytes_FromObject(PyObject *o)
    *Return value: New reference.*

   返回字节表示实现缓冲区协议的对象*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)

   通过输出变量 *buffer* 和 *length* 返回以 null 为终止符的对象 *obj*
   的内容。

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

   该缓冲区指向 *obj* 的内部缓冲，它的末尾包含一个额外的空字节（不算在
   *length* 当中）。 该数据不可通过任何方式来修改，除非是刚使用
   "PyBytes_FromStringAndSize(NULL, size)" 创建该对象。 它不可被撤销分
   配。 如果 *obj* 根本不是一个字节串对象，则
   "PyBytes_AsStringAndSize()" 将返回 "-1" 并引发 "TypeError"。

   3.5 版更變: 以前，当字节串对象中出现嵌入的空字节时将引发
   "TypeError"。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)

   在 **bytes* 中创建新的字节串对象，其中包含添加到 *bytes* 的
   *newpart* 的内容；调用者将获得新的引用。 对 *bytes* 原值的引用将被
   收回。 如果无法创建新对象，对 *bytes* 的旧引用仍将被丢弃且 **bytes*
   的值将被设为 "NULL"；并将设置适当的异常。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)

   在 **bytes* 中创建新的字节串对象，其中包含添加到 *bytes* 的
   *newpart* 的内容。 此版本会减少 *newpart* 的引用计数。

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

   改变字节串大小的一种方式，即使其为“不可变对象”。 此方式仅用于创建全
   新的字节串对象；如果字节串在代码的其他部分已知则不可使用此方式。 如
   果输入字节串对象的引用计数不为一则调用此函数将报错。 传入一个现有字
   节串对象的地址作为 lvalue（它可能会被写入），并传入希望的新大小。
   当成功时，**bytes* 将存放改变大小后的字节串对象并返回 "0"；**bytes*
   中的地址可能与其输入值不同。 如果重新分配失败，则 **bytes* 上的原字
   节串对象将被撤销分配，**bytes* 会被设为 "NULL"，同时设置
   "MemoryError" 并返回 "-1"。
