# バイトオブジェクト

These functions raise `TypeError` when expecting a bytes parameter and called with a non-bytes parameter.

`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 文字列中のフォーマット文字と厳密に関連付けられていなければなりません。下記のフォーマット文字が使用できます:

  書式指定文字 | 型 | 備考
  --- | --- | ---
  `%%` | 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` が付きます。

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

  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)
  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 の中身へのポインタを返します。 ポインタは、 `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)

  obj のnull 終端された中身を、出力用の変数 buffer と length を介して返します。

  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)

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

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

  newpart の内容を bytes の後ろに連結した新しいバイトオブジェクトを *bytes に生成します; この関数は、 newpart の参照カウントをデクリメントします。

int `_PyBytes_Resize`(PyObject **bytes, Py_ssize_t newsize)

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