Bytes 物件

當這些函式需要 bytes 引數但以非 bytes 引數呼叫時，它們會引發 TypeError。

type PyBytesObject

此 PyObject 的子型別表示一個 Python bytes 物件。

PyTypeObject PyBytes_Type
作為 穩定 ABI 的一部分。

此 PyTypeObject 例項表示 Python bytes 型別；它與 Python 層中的 bytes 物件相同。

int PyBytes_Check(PyObject *o)

如果物件 o 是一個 bytes 物件或 bytes 型別的子型別的例項，則返回 true。此函式始終成功。

int PyBytes_CheckExact(PyObject *o)

如果物件 o 是一個 bytes 物件，但不是 bytes 型別的子型別的例項，則返回 true。此函式始終成功。

PyObject *PyBytes_FromString(const char *v)
返回值: 新引用。 穩定ABI 的一部分。

成功時返回一個新的 bytes 物件，其值為字串 v 的副本，失敗時返回 NULL。引數 v 不得為 NULL；它不會被檢查。

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
返回值: 新引用。 穩定ABI 的一部分。

成功時返回一個新的 bytes 物件，其值為字串 v 的副本且長度為 len，失敗時返回 NULL。如果 v 為 NULL，則 bytes 物件的內容未初始化。

PyObject *PyBytes_FromFormat(const char *format, ...)
返回值: 新引用。 穩定ABI 的一部分。

接受 C printf() 風格的 format 字串和可變數量的引數，計算結果 Python bytes 物件的大小，並返回一個將值格式化到其中的 bytes 物件。可變引數必須是 C 型別，並且必須與 format 字串中的格式字元完全對應。允許以下格式字元：

格式字元

型別

註釋

%%

不適用

字面量 % 字元。

%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*

一個以 null 結尾的 C 字元陣列。

%p

const void*

C 指標的十六進位制表示。大致等價於 printf("%p")，不同之處在於它保證以字面量 0x 開頭，無論平臺的 printf 輸出什麼。

未識別的格式字元會導致格式字串的其餘部分按原樣複製到結果物件中，任何額外的引數都會被丟棄。

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
返回值: 新引用。 穩定ABI 的一部分。

與 PyBytes_FromFormat() 相同，不同之處在於它只接受兩個引數。

PyObject *PyBytes_FromObject(PyObject *o)
返回值: 新引用。 穩定ABI 的一部分。

返回實現緩衝區協議的物件 o 的 bytes 表示。

Py_ssize_t PyBytes_Size(PyObject *o)
作為 穩定 ABI 的一部分。

返回 bytes 物件 o 中 bytes 的長度。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

類似於 PyBytes_Size()，但沒有錯誤檢查。

char *PyBytes_AsString(PyObject *o)
作為 穩定 ABI 的一部分。

返回指向 o 內容的指標。該指標指向 o 的內部緩衝區，該緩衝區由 len(o) + 1 個位元組組成。緩衝區中的最後一個位元組始終為 null，無論是否存在其他 null 位元組。資料不得以任何方式修改，除非該物件是使用 PyBytes_FromStringAndSize(NULL, size) 剛剛建立的。它不得被釋放。如果 o 根本不是 bytes 物件，PyBytes_AsString() 返回 NULL 並引發 TypeError。

char *PyBytes_AS_STRING(PyObject *string)

類似於 PyBytes_AsString()，但沒有錯誤檢查。

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
作為 穩定 ABI 的一部分。

透過輸出變數 buffer 和 length 返回物件 obj 的以 null 結尾的內容。成功時返回 0。

如果 length 為 NULL，則 bytes 物件可能不包含嵌入的 null 位元組；如果包含，則函式返回 -1 並引發 ValueError。

緩衝區指向 obj 的內部緩衝區，其中末尾包含一個額外的 null 位元組（未計入 length）。資料不得以任何方式修改，除非該物件是使用 PyBytes_FromStringAndSize(NULL, size) 剛剛建立的。它不得被釋放。如果 obj 根本不是 bytes 物件，PyBytes_AsStringAndSize() 返回 -1 並引發 TypeError。

3.5 版本中有所改變: 之前，當 bytes 物件中遇到嵌入的 null 位元組時會引發 TypeError。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
作為 穩定 ABI 的一部分。

在 *bytes 中建立一個新的 bytes 物件，其中包含 newpart 的內容追加到 bytes 之後；呼叫者將擁有新的引用。對 bytes 舊值的引用將被盜用。如果無法建立新物件，對 bytes 的舊引用仍將被丟棄，並且 *bytes 的值將設定為 NULL；將設定適當的異常。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
作為 穩定 ABI 的一部分。

在 *bytes 中建立一個新的 bytes 物件，其中包含 newpart 的內容追加到 bytes 之後。此版本釋放對 newpart 的 強引用（即減少其引用計數）。

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)

類似於 Python 中的 sep.join(iterable)。

sep 必須是 Python bytes 物件。（請注意，PyUnicode_Join() 接受 NULL 分隔符並將其視為一個空格，而 PyBytes_Join() 不接受 NULL 分隔符。）

iterable 必須是一個可迭代物件，產生實現 緩衝區協議 的物件。

成功時，返回一個新的 bytes 物件。出錯時，設定一個異常並返回 NULL。

在 3.14 版本加入。

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

調整 bytes 物件的大小。newsize 將是 bytes 物件的新長度。您可以將其視為建立一個新的 bytes 物件並銷燬舊的，只是更有效。將現有 bytes 物件的地址作為左值傳遞（它可以被寫入），以及所需的新大小。成功時，*bytes 持有調整大小後的 bytes 物件，並返回 0；*bytes 中的地址可能與其輸入值不同。如果重新分配失敗，*bytes 處的原始 bytes 物件將被釋放，*bytes 將設定為 NULL，設定 MemoryError，並返回 -1。