バイトオブジェクト
******************

下記の関数は、バイトオブジェクトを期待している引数にバイトオブジェクト
でないパラメタを指定して呼び出されると、 "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"
   の場合、バイトオブジェクトの中身は初期化されていません。

   Soft deprecated since version 3.15: Use the "PyBytesWriter" API
   instead of "PyBytes_FromStringAndSize(NULL, len)".

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] 整数指定子 (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.*

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

   注釈:

     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.

   Soft deprecated since version 3.15: Use the "PyBytesWriter" API
   instead.

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.


PyBytesWriter
*************

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

Added in version 3.15.

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()". This function does not
   overallocate.

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


高レベル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.

   The function cannot fail.

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

   The function cannot fail.


低レベル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. This function typically overallocates to achieve
   amortized performance when resizing multiple times.

   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. This function typically overallocates to achieve amortized
   performance when resizing multiple times.

   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;
