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

下記の関数は、文字列オブジェクトを期待している引数に文字列オブジェクトでないパラメタを指定して呼び出されると、 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 long	C の printf("%llu") と全く同じ。
%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 エイリアスもありません。