バイトオブジェクト

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクトでないパラメタを指定して呼び出されると、 TypeError を送出します。

type PyBytesObject

この PyObject のサブタイプは、Python バイトオブジェクトを表します。

PyTypeObject PyBytes_Type
Part of the Stable ABI.

この 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. Part of the Stable ABI.

成功時に、文字列 v のコピーを値とする新しいバイトオブジェクトを返し、失敗時に NULL を返します。 引数 vNULL であってはなりません; そのチェックは行われません。

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
Return value: New reference. Part of the Stable ABI.

成功時に、文字列 v のコピーを値とする長さ len の新しいバイトオブジェクトを返し、失敗時に NULL を返します。 引数 vNULL の場合、バイトオブジェクトの中身は初期化されていません。

PyObject *PyBytes_FromFormat(const char *format, ...)
Return value: New reference. Part of the Stable ABI.

C 関数の printf() スタイルの format 文字列と可変長の引数を取り、結果のPython バイトオブジェクトのサイズを計算し、値を指定した書式にしたがって変換したバイトオブジェクトを返します。可変長の引数は C のデータ型でなければならず、 format 文字列中のフォーマット文字と厳密に関連付けられていなければなりません。下記のフォーマット文字が使用できます:

書式指定文字

備考

%%

n/a

リテラルの % 文字

%c

int

C の整数型で表現される単一のバイト。

%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 ポインタの 16 進表記。printf("%p") とほとんど同じですが、プラットフォームにおける printf の定義に関わりなく先頭にリテラル 0x が付きます。

識別できない書式指定文字があった場合、残りの書式文字列はそのまま結果のオブジェクトにコピーされ、残りの引数は無視されます。

PyObject *PyBytes_FromFormatV(const char *format, va_list vargs)
Return value: New reference. Part of the Stable ABI.

ちょうど2つの引数を取ることを除いて、 PyBytes_FromFormat() と同じです。

PyObject *PyBytes_FromObject(PyObject *o)
Return value: New reference. Part of the Stable ABI.

バッファプロトコルを実装するオブジェクト o のバイト表現を返します。

Py_ssize_t PyBytes_Size(PyObject *o)
Part of the Stable ABI.

バイトオブジェクト o のバイト単位の長さを返します。

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

PyBytes_Size() に似ていますが、エラーチェックを行いません。

char *PyBytes_AsString(PyObject *o)
Part of the Stable ABI.

o の中身へのポインタを返します。 ポインタは、 len(o) + 1 バイトからなる o の内部バッファを参照します。 他に null のバイトがあるかどうかにかかわらず、バッファの最後のバイトは必ず null になります。 PyBytes_FromStringAndSize(NULL, size) で生成された場合を除いて、データを修正してはなりません。 またポインタを解放(deallocated)してはなりません。 もし、 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)
Part of the Stable ABI.

Return the null-terminated contents of the object obj through the output variables buffer and length. Returns 0 on success.

length の値が NULL の場合、バイトオブジェクトが null バイトを含まない可能性があります。その場合、関数は -1 を返し、 ValueError を送出します。

buffer は obj の内部バッファを参照していて、これには末尾の null バイトも含んでいます (これは length には数えられません)。 オブジェクトが PyBytes_FromStringAndSize(NULL, size) で生成された場合を除いて、何があってもデータを改変してはいけません。 オブジェクトを解放 (deallocate) してもいけません。 obj が bytes オブジェクトでなかった場合は、 PyBytes_AsStringAndSize()-1 を返し TypeError を送出します。

バージョン 3.5 で変更: 以前は bytes オブジェクトにヌルバイトが埋め込まれていたときに TypeError を送出していました。

void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI.

newpart の内容を bytes の後ろに連結した新しいバイトオブジェクトを *bytes に生成します。呼び出し側は新しい参照を所有します。 bytes の古い値の参照は盗まれます。 もし新しいオブジェクトが生成できない場合、古い bytes の参照は放棄され、 *bytes の値は NULL に設定されます; 適切な例外が設定されます。

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
Part of the Stable ABI.

Create a new bytes object in *bytes containing the contents of newpart appended to bytes. This version releases the strong reference to newpart (i.e. decrements its reference count).

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

本来 "変更不可能 (immutable)" なバイトオブジェクトをリサイズする方法です。 作成されたばかりのバイトオブジェクトにのみこれをしようしてください; 他のコードですでに使用されている可能性のあるバイトオブジェクトに使用してはいけません。 入力されたバイトオブジェクトの参照カウントが 1 でない場合、この関数はエラーになります。 左辺値として存在する (つまり書き込み可能な) バイトオブジェクトのアドレスを受け取り、新しいサイズを要求します。 成功時には、*bytes はリサイズされたバイトオブジェクトを保持し、0 が返されます; *bytes のアドレスは入力された際のアドレスと異なるかもしれません。 再割り当て (reallocation) が失敗した場合、 *bytes が元々指してしたバイトオブジェクトを解放し、*bytesNULL に設定し、 MemoryError を設定し、そして -1 が返されます。