# バイトオブジェクト

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクトでないパラメタを指定して呼び出されると、 `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. Thread safety: Atomic.

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

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

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

PyObject *PyBytes_FromFormat(const char *format, ...)
  戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Atomic.

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

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

PyObject *PyBytes_FromObject(PyObject *o)
  戻り値: 新しい参照。 次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

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

  注釈

  If the object implements the buffer protocol, then the buffer must not be mutated while the bytes object is being created.

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

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

Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
  Thread safety: Atomic.

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

char *PyBytes_AsString(PyObject *o)
  次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  o の中身へのポインタを返します。 ポインタは、 `len(o) + 1` バイトからなる o の内部バッファを参照します。 他に null のバイトがあるかどうかにかかわらず、バッファの最後のバイトは必ず null になります。 `PyBytes_FromStringAndSize(NULL, size)` で生成された場合を除いて、データを修正してはなりません。 またポインタを解放（deallocated）してはなりません。 もし、 o が bytes オブジェクトでなければ、 `PyBytes_AsString()` は `NULL` を返し `TypeError` を送出します。

char *PyBytes_AS_STRING(PyObject *string)
  Thread safety: Safe to call from multiple threads with external synchronization only.

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

int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
  次に属します: Stable ABI. Thread safety: Safe to call from multiple threads with external synchronization only.

  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. Thread safety: Safe for concurrent use on the same object.

  Create a new bytes object in *bytes containing the contents of newpart appended to bytes; the caller will own the new reference. The reference to the old value of bytes will be "stolen". If the new object cannot be created, the old reference to bytes will still be "stolen", the value of *bytes will be set to `NULL`, and the appropriate exception will be set.

  注釈

  If newpart implements the buffer protocol, then the buffer must not be mutated while the new bytes object is being created.

void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
  次に属します: Stable ABI. Thread safety: Safe for concurrent use on the same object.

  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).

  注釈

  If newpart implements the buffer protocol, then the buffer must not be mutated while the new bytes object is being created.

PyObject *PyBytes_Join(PyObject *sep, PyObject *iterable)
  Thread safety: Safe for concurrent use on the same object.

  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.

  注釈

  If iterable objects implement the buffer protocol, then the buffers must not be mutated while the new bytes object is being created.

int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
  Thread safety: Safe to call without external synchronization on distinct objects.

  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.

PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
  次に属します: Stable ABI. Thread safety: Atomic.

  Get the string representation of bytes. This function is currently used to implement `bytes.__repr__()` in Python.

  This function does not do type checking; it is undefined behavior to pass bytes as a non-bytes object or `NULL`.

  If smartquotes is true, the representation will use a double-quoted string instead of single-quoted string when single-quotes are present in bytes. For example, the byte string `'Python'` would be represented as `b"'Python'"` when smartquotes is true, or `b'\'Python\''` when it is false.

  On success, this function returns a strong reference to a `str` object containing the representation. On failure, this returns `NULL` with an exception set.

PyObject *PyBytes_DecodeEscape(const char *s, Py_ssize_t len, const char *errors, Py_ssize_t unicode, const char *recode_encoding)
  次に属します: Stable ABI. Thread safety: Atomic.

  Unescape a backslash-escaped string s. s must not be `NULL`. len must be the size of s.

  errors must be one of `"strict"`, `"replace"`, or `"ignore"`. If errors is `NULL`, then `"strict"` is used by default.

  On success, this function returns a strong reference to a Python `bytes` object containing the unescaped string. On failure, this function returns `NULL` with an exception set.

  バージョン 3.9 で変更: unicode and recode_encoding are now unused.