文字列とバイト列オブジェクト
****************************

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

注釈: これらの関数群は Python 3.x では PyBytes_* へリネームされます
  。移植 を容易にするために、特に注釈されていない限り、 3.x で利用でき
  る PyBytes 関数群は同等の PyString_* 関数へのエイリアスにされていま
  す。

PyStringObject

   この "PyObject" のサブタイプは Python の文字列オブジェクトを表現し
   ます。

PyTypeObject PyString_Type

   この "PyTypeObject" のインスタンスは Python の文字列型を表現します;
   このオブジェクトは Python レイヤにおける "str" や
   "types.StringType" と同じです。 .

int PyString_Check(PyObject *o)

   *o* が文字列型か文字列型のサブタイプであるときに真を返します。

   バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.

int PyString_CheckExact(PyObject *o)

   *o* が文字列型で、かつ文字列型のサブタイプでないときに真を返します
   。

   バージョン 2.2 で追加.

PyObject* PyString_FromString(const char *v)
    *Return value: New reference.*

   *v* を値に持つ文字列オブジェクトを返します。失敗すると *NULL* を返
   します。パラメタ *v* は *NULL* であってはなりません; *NULL* かどう
   かはチェックしません。

PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)
    *Return value: New reference.*

   値が *v* で長さが *len* の新たな文字列オブジェクトを返します。失敗
   すると *NULL* を返します。 *v* が *NULL* の場合、文字列の中身は未初
   期化の状態になります。

   バージョン 2.5 で変更: この関数は以前は *len* の型に "int" を利用し
   ていました。この変更により、 64 bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyString_FromFormat(const char *format, ...)
    *Return value: New reference.*

   C 関数 "printf()" 形式の *format* 文字列と可変個の引数をとり、書式
   化済みの文字列長を計算した上で、書式化を行った結果を値とする Python
   文字列にして返します。可変個の引数部は C のデータ型でなくてはならず
   、かつ *format* 文字列内の書式指定文字 (format character) に一致す
   る型でなくてはなりません。利用できる書式化文字は以下の通りです:

   +---------------------+-----------------+----------------------------------+
   | 書式指定文字        | 型              | コメント                         |
   +=====================+=================+==================================+
   | "%%"                | *n/a*           | 文字 % のリテラル。              |
   +---------------------+-----------------+----------------------------------+
   | "%c"                | int             | C の整数型で表現される単一の文字 |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%d"                | int             | C の "printf("%d")" と全く同じ。 |
   +---------------------+-----------------+----------------------------------+
   | "%u"                | unsigned int    | C の "printf("%u")" と全く同じ。 |
   +---------------------+-----------------+----------------------------------+
   | "%ld"               | long            | C の "printf("%ld")" と全く同じ  |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%lu"               | unsigned long   | C の "printf("%lu")" と全く同じ  |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%lld"              | long long       | C の "printf("%lld")" と全く同じ |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%llu"              | unsigned long   | C の "printf("%llu")" と全く同じ |
   |                     | long            | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%zd"               | Py_ssize_t      | C の "printf("%zd")" と全く同じ  |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%zu"               | size_t          | C の "printf("%zu")" と全く同じ  |
   |                     |                 | 。                               |
   +---------------------+-----------------+----------------------------------+
   | "%i"                | int             | C の "printf("%i")" と全く同じ。 |
   +---------------------+-----------------+----------------------------------+
   | "%x"                | int             | C の "printf("%x")" と全く同じ。 |
   +---------------------+-----------------+----------------------------------+
   | "%s"                | char*           | null で終端された C の文字列。   |
   +---------------------+-----------------+----------------------------------+
   | "%p"                | void*           | C ポインタの 16 進表記。         |
   |                     |                 | "printf("%p")" とほとんど同じだ  |
   |                     |                 | が、プラッ トフォームにおける    |
   |                     |                 | "printf" の定義に関わりなく先頭  |
   |                     |                 | にリテラル "0x" が付きます。     |
   +---------------------+-----------------+----------------------------------+

   識別できない書式指定文字があった場合、残りの書式文字列はそのまま出
   力文字列にコピーされ、残りの引数は無視されます。

   注釈: *"%lld"* と *"%llu"* 書式指定文字は "HAVE_LONG_LONG" が定義
     されて いる時だけ利用できます。

   バージョン 2.7 で変更: *"%lld"* と *"%llu"* のサポートが追加されま
   した。

PyObject* PyString_FromFormatV(const char *format, va_list vargs)
    *Return value: New reference.*

   "PyString_FromFormat()" と同じです。ただし、こちらの関数は二つしか
   引数をとりません。

Py_ssize_t PyString_Size(PyObject *string)

   文字列オブジェクト *string* 内の文字列値の長さを返します。

   バージョン 2.5 で変更: この関数は以前は "int" を返していました。こ
   の変更により、 64 bit システムを正しくサポートするには修正が必要に
   なります。

Py_ssize_t PyString_GET_SIZE(PyObject *string)

   "PyString_Size()" をマクロで実装したもので、エラーチェックを行いま
   せん。

   バージョン 2.5 で変更: このマクロは以前は "int" を返していました。
   この変更により、 64 bit システムを正しくサポートするには修正が必要
   になります。

char* PyString_AsString(PyObject *string)

   *string* の中身を NUL 文字終端された表現で返します。ポインタは
   *string* オブジェクトの内部バッファを指し、バッファのコピーを指すわ
   けではありません。 "PyString_FromStringAndSize(NULL, size)" を使っ
   て生成した文字列でない限り、バッファ内のデータはいかなる変更もして
   はなりません。この文字列をデアロケートしてはなりません。 *string*
   が Unicode オブジェクトの場合、この関数は *string* のデフォルトエン
   コーディング版を計算し、デフォルトエンコーディング版に対して操作を
   行います。 *string* が文字列オブジェクトですらない場合、
   "PyString_AsString()" は *NULL* を返して "TypeError" を送出します。

char* PyString_AS_STRING(PyObject *string)

   "PyString_AsString()" をマクロで実装したもので、エラーチェックを行
   いません。文字列オブジェクトだけをサポートします; Unicode オブジェ
   クトを渡してはなりません。

int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)

   *obj* の中身を NUL 文字終端された表現にして、出力用の変数 *buffer*
   と *length* を使って返します。

   この関数は文字列オブジェクトと Unicode オブジェクトのどちらも入力と
   して受理します。 Unicode オブジェクトの場合、オブジェクトをデフォル
   トエンコーディングでエンコードしたバージョン (default encoded
   version) を返します。 *length* が *NULL* の場合、値を返させるバッフ
   ァには NUL 文字を入れてはなりません; NUL 文字が入っている場合、関数
   は "-1" を返し、 "TypeError" を送出します。

   *buffer* は *obj* の内部文字列バッファを参照し、バッファのコピーを
   参照するわけではありません。 "PyString_FromStringAndSize(NULL,
   size)" を使って生成した文字列でない限り、バッファ内のデータはいかな
   る変更もしてはなりません。この文字列をデアロケートしてはなりません
   。 *string* が Unicode オブジェクトの場合、この関数は *string* のデ
   フォルトエンコーディング版を計算し、デフォルトエンコーディング版に
   対して操作を行います。 *string* が文字列オブジェクトですらない場合
   、 "PyString_AsStringAndSize()" は "-1" を返して "TypeError" を送出
   します。

   バージョン 2.5 で変更: この関数は以前は *length* に "int *" 型を使
   用していました。この変更により、 64 bit システムを正しくサポートす
   るには修正が必要になります。

void PyString_Concat(PyObject **string, PyObject *newpart)

   新しい文字列オブジェクトを **string* に作成し、 *newpart* の内容を
   *string* に追加します; 呼び出し側は新たな参照を所有することになりま
   す。 *string* の以前の値に対する参照は盗み取られます。新たな文字列
   を生成できなければ、 *string* に対する古い参照は無視され、
   **string* の値は *NULL* に設定されます; その際、適切な例外情報が設
   定されます。

void PyString_ConcatAndDel(PyObject **string, PyObject *newpart)

   新しい文字列オブジェクトを **string* に作成し、 *newpart* の内容を
   *string* に追加します。こちらのバージョンの関数は *newpart* への参
   照をデクリメントします。

int _PyString_Resize(PyObject **string, Py_ssize_t newsize)

   "変更不能" である文字列オブジェクトをサイズ変更する手段です。新たな
   文字列オブジェクトを作成するときにのみ使用してください; 文字列がす
   でにコードの他の部分で使われているかもしれない場合には、この関数を
   使ってはなりません。入力する文字列オブジェクトの参照カウントが 1 で
   ない場合、この関数を呼び出すとエラーになります。左側値には、既存の
   文字列オブジェクトのアドレスを渡し (このアドレスには書き込み操作が
   起きるかもしれません)、新たなサイズを指定します。成功した場合、
   **string* はサイズ変更された文字列オブジェクトを保持し、 "0" が返さ
   れます; **string* の値は、入力したときの値と異なっているかもしれま
   せん。文字列の再アロケーションに失敗した場合、 **string* に入ってい
   た元の文字列オブジェクトを解放し、 **string* を *NULL* にセットし、
   メモリ例外をセットし、 "-1" を返します。

   バージョン 2.5 で変更: この関数は以前は *newsize* の型に "int" を利
   用していました。この変更により、 64 bit システムを正しくサポートす
   るには修正が必要になります。

PyObject* PyString_Format(PyObject *format, PyObject *args)
    *Return value: New reference.*

   新たな文字列オブジェクトを *format* と *args* から生成します。
   "format % args" と似た働きです。引数 *args* はタプルまたは辞書でな
   ければなりません。

void PyString_InternInPlace(PyObject **string)

   引数 **string* をインプレースで隔離 (intern) します。引数は Python
   文字列オブジェクトを指すポインタへのアドレスでなくてはなりません。
   **string* と等しい、すでに隔離済みの文字列が存在する場合、そのオブ
   ジェクトを **string* に設定します (かつ、元の文字列オブジェクトの参
   照カウントをデクリメントし、すでに隔離済みの文字列オブジェクトの参
   照カウントをインクリメントします)。 (補足: 参照カウントについては沢
   山説明して来ましtが、この関数は参照カウント中立 (reference-count-
   neutral) と考えてください; この関数では、関数の呼び出し後にオブジェ
   クトに対して参照の所有権を持てるのは、関数を呼び出す前にすでに所有
   権を持っていた場合に限ります。)

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。

PyObject* PyString_InternFromString(const char *v)
    *Return value: New reference.*

   "PyString_FromString()" と "PyString_InternInPlace()" を組み合わせ
   たもので、隔離済みの新たな文字列オブジェクトを返すか、同じ値を持つ
   すでに隔離済みの文字列オブジェクトに対する新たな ("所有権を得た")
   参照を返します。

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。

PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
    *Return value: New reference.*

   *size* からなるエンコード済みのバッファ *s* を *encoding* の名前で
   登録されている codec に渡してデコードし、オブジェクトを生成します。
   *encoding* および *errors* は組み込み関数 "unicode()" に与える同名
   のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の
   codec レジストリを使って行います。codec が例外を送出した場合には
   *NULL* を返します。

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
    *Return value: New reference.*

   文字列オブジェクトを *encoding* の名前で登録されている codec に渡し
   てデコードし、Python オブジェクトを返します。 *encoding* および
   *errors* は文字列型の "encode()" メソッドに与える同名のパラメタと同
   じ意味を持ちます。使用する codec の検索は、 Python の codec レジス
   トリを使って行います。codec が例外を送出した場合には *NULL* を返し
   ます。

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。

PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)
    *Return value: New reference.*

   *size* で指定されたサイズの "char" バッファを *encoding* の名前で登
   録されている codec に渡してエンコードし、 Python オブジェクトを返し
   ます。 *encoding* および *errors* は文字列型の "encode()" メソッド
   に与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は
   、 Python の codec レジストリを使って行います。codec が例外を送出し
   た場合には *NULL* を返します。

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。

   バージョン 2.5 で変更: この関数は以前は *size* の型に "int" を利用
   していました。この変更により、 64bit システムを正しくサポートするに
   は修正が必要になります。

PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
    *Return value: New reference.*

   エンコード名 *encoding* で登録された codec を使って文字列オブジェク
   トをエンコードし、その結果を Python オブジェクトとして返します。
   *encoding* および *errors* は文字列型の "encode()" メソッドに与える
   同名のパラメタと同じ意味を持ちます。使用する codec の検索は、
   Python の codec レジストリを使って行います。codec が例外を送出した
   場合には *NULL* を返します。

   注釈: この関数は 3.x では利用できず、 PyBytes エイリアスもありま
     せん。
