バイトオブジェクト

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

type PyBytesObject

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

PyTypeObject PyBytes_Type
次に属します: 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)
戻り値: 新しい参照。 次に属します: Stable ABI.

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

PyObject *PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
戻り値: 新しい参照。 次に属します: Stable ABI.

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

バージョン 3.15 で非推奨: PyBytes_FromStringAndSize(NULL, len) is soft deprecated, use the PyBytesWriter API instead.

PyObject *PyBytes_FromFormat(const char *format, ...)
戻り値: 新しい参照。 次に属します: 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)
戻り値: 新しい参照。 次に属します: Stable ABI.

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

PyObject *PyBytes_FromObject(PyObject *o)
戻り値: 新しい参照。 次に属します: Stable ABI.

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

Py_ssize_t PyBytes_Size(PyObject *o)
次に属します: Stable ABI.

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

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)

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

char *PyBytes_AsString(PyObject *o)
次に属します: 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)
次に属します: 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)
次に属します: Stable ABI.

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

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
次に属します: 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).

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

Similar to sep.join(iterable) in Python.

sep must be Python bytes object. (Note that PyUnicode_Join() accepts NULL separator and treats it as a space, whereas PyBytes_Join() doesn't accept NULL separator.)

iterable must be an iterable object yielding objects that implement the buffer protocol.

On success, return a new bytes object. On error, set an exception and return NULL.

Added in version 3.14.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)

Resize a bytes object. newsize will be the new length of the bytes object. You can think of it as creating a new bytes object and destroying the old one, only more efficiently. Pass the address of an existing bytes object as an lvalue (it may be written into), and the new size desired. On success, *bytes holds the resized bytes object and 0 is returned; the address in *bytes may differ from its input value. If the reallocation fails, the original bytes object at *bytes is deallocated, *bytes is set to NULL, MemoryError is set, and -1 is returned.

バージョン 3.15 で非推奨: The function is soft deprecated, use the PyBytesWriter API instead.

PyBytesWriter

The PyBytesWriter API can be used to create a Python bytes object.

Added in version 3.15.0a0 (unreleased).

type PyBytesWriter

A bytes writer instance.

The API is not thread safe: a writer should only be used by a single thread at the same time.

The instance must be destroyed by PyBytesWriter_Finish() on success, or PyBytesWriter_Discard() on error.

Create, Finish, Discard

PyBytesWriter *PyBytesWriter_Create(Py_ssize_t size)

Create a PyBytesWriter to write size bytes.

If size is greater than zero, allocate size bytes, and set the writer size to size. The caller is responsible to write size bytes using PyBytesWriter_GetData().

On error, set an exception and return NULL.

size must be positive or zero.

PyObject *PyBytesWriter_Finish(PyBytesWriter *writer)

Finish a PyBytesWriter created by PyBytesWriter_Create().

On success, return a Python bytes object. On error, set an exception and return NULL.

The writer instance is invalid after the call in any case. No API can be called on the writer after PyBytesWriter_Finish().

PyObject *PyBytesWriter_FinishWithSize(PyBytesWriter *writer, Py_ssize_t size)

Similar to PyBytesWriter_Finish(), but resize the writer to size bytes before creating the bytes object.

PyObject *PyBytesWriter_FinishWithPointer(PyBytesWriter *writer, void *buf)

Similar to PyBytesWriter_Finish(), but resize the writer using buf pointer before creating the bytes object.

Set an exception and return NULL if buf pointer is outside the internal buffer bounds.

Function pseudo-code:

Py_ssize_t size = (char*)buf - (char*)PyBytesWriter_GetData(writer);
return PyBytesWriter_FinishWithSize(writer, size);
void PyBytesWriter_Discard(PyBytesWriter *writer)

Discard a PyBytesWriter created by PyBytesWriter_Create().

Do nothing if writer is NULL.

The writer instance is invalid after the call. No API can be called on the writer after PyBytesWriter_Discard().

High-level API

int PyBytesWriter_WriteBytes(PyBytesWriter *writer, const void *bytes, Py_ssize_t size)

Grow the writer internal buffer by size bytes, write size bytes of bytes at the writer end, and add size to the writer size.

If size is equal to -1, call strlen(bytes) to get the string length.

On success, return 0. On error, set an exception and return -1.

int PyBytesWriter_Format(PyBytesWriter *writer, const char *format, ...)

Similar to PyBytes_FromFormat(), but write the output directly at the writer end. Grow the writer internal buffer on demand. Then add the written size to the writer size.

On success, return 0. On error, set an exception and return -1.

Getters

Py_ssize_t PyBytesWriter_GetSize(PyBytesWriter *writer)

Get the writer size.

void *PyBytesWriter_GetData(PyBytesWriter *writer)

Get the writer data: start of the internal buffer.

The pointer is valid until PyBytesWriter_Finish() or PyBytesWriter_Discard() is called on writer.

Low-level API

int PyBytesWriter_Resize(PyBytesWriter *writer, Py_ssize_t size)

Resize the writer to size bytes. It can be used to enlarge or to shrink the writer.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

size must be positive or zero.

int PyBytesWriter_Grow(PyBytesWriter *writer, Py_ssize_t grow)

Resize the writer by adding grow bytes to the current writer size.

Newly allocated bytes are left uninitialized.

On success, return 0. On error, set an exception and return -1.

size can be negative to shrink the writer.

void *PyBytesWriter_GrowAndUpdatePointer(PyBytesWriter *writer, Py_ssize_t size, void *buf)

Similar to PyBytesWriter_Grow(), but update also the buf pointer.

The buf pointer is moved if the internal buffer is moved in memory. The buf relative position within the internal buffer is left unchanged.

On error, set an exception and return NULL.

buf must not be NULL.

Function pseudo-code:

Py_ssize_t pos = (char*)buf - (char*)PyBytesWriter_GetData(writer);
if (PyBytesWriter_Grow(writer, size) < 0) {
    return NULL;
}
return (char*)PyBytesWriter_GetData(writer) + pos;