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

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

PyBytesObject

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

PyTypeObject PyBytes_Type

   この "PyTypeObject" のインスタンスは、Python バイト型を表します;
   Pythonレイヤの "bytes" と同じオブジェクトです。

int PyBytes_Check(PyObject *o)

   オブジェクト *o* がバイトオブジェクトか、またはbytes型のサブタイプ
   のインスタンスである場合に真を返します。

int PyBytes_CheckExact(PyObject *o)

   オブジェクト *o* がバイトオブジェクトであり、かつ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] 整数指定子 (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" が返されます。
