##
7.3.1 文字列オブジェクト (string object)

以下の関数では、文字列が渡されるはずのパラメタに非文字列が渡された 場合に `TypeError` を送出します。

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

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

int `PyString_Check`( | PyObject *o)

  o が文字列型か文字列型のサブタイプであるときに真を返します。 バージョン2.2 以降で変更された 仕様: サブタイプを引数にとれるようになりました

int `PyString_CheckExact`( | PyObject *o)

  o が文字列型で、かつ文字列型のサブタイプでないときに真を返します。 バージョン2.2 以降で新規追加された 仕様です。

PyObject* `PyString_FromString`( | const char *v)

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

PyObject* `PyString_FromStringAndSize`( | const char *v, int len)

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

PyObject* `PyString_FromFormat`( | const char *format, ...)

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

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

PyObject* `PyString_FromFormatV`( | const char *format, va_list vargs)

  戻り値: 新たな参照.
  `PyString_FromFormat()` と同じです。ただし、こちらの関数は 二つしか引数をとりません。

int `PyString_Size`( | PyObject *string)

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

int `PyString_GET_SIZE`( | PyObject *string)

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

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, int *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_AsStringAnsSize()` は `NULL` を返して `TypeError` を送出します。

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, int newsize)

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

PyObject* `PyString_Format`( | PyObject *format, PyObject *args)

  戻り値: 新たな参照.
  新たな文字列オブジェクトを format と args から生成します。 `format % args` と似た働きです。引数 args はタプルでなければなりません。

void `PyString_InternInPlace`( | PyObject **string)

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

PyObject* `PyString_InternFromString`( | const char *v)

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

PyObject* `PyString_Decode`( | const char *s, int size, const char *encoding, const char *errors)

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

PyObject* `PyString_AsDecodedObject`( | PyObject *str, const char *encoding, const char *errors)

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

PyObject* `PyString_Encode`( | const char *s, int size, const char *encoding, const char *errors)

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

PyObject* `PyString_AsEncodedObject`( | PyObject *str, const char *encoding, const char *errors)

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