以下の関数では、文字列が渡されるはずのパラメタに非文字列が渡された場合に TypeError を送出します。
ノート
これらの関数群は Python 3.x では PyBytes_* へリネームされます。移植を容易にするために、特に注釈されていない限り、 3.x で利用できる PyBytes 関数群は同等の PyString_* 関数へのエイリアスにされています。
この PyTypeObject のインスタンスは Python の文字列型を表現します; このオブジェクトは Python レイヤにおける str や types.StringType と同じです。 .
o が文字列型か文字列型のサブタイプであるときに真を返します。
バージョン 2.2 で変更: サブタイプを引数にとれるようになりました.
v を値に持つ文字列オブジェクトを返します。失敗すると NULL を返します。パラメタ v は NULL であってはなりません; NULL かどうかはチェックしません。
値が v で長さが len の新たな文字列オブジェクトを返します。失敗すると NULL を返します。 v が NULL の場合、文字列の中身は未初期化の状態になります。
バージョン 2.5 で変更: この関数は以前は len の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
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” のサポートが追加されました。
PyString_FromFormat() と同じです。ただし、こちらの関数は二つしか引数をとりません。
文字列オブジェクト string 内の文字列値の長さを返します。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
PyString_Size() をマクロで実装したもので、エラーチェックを行いません。
バージョン 2.5 で変更: この関数は以前は int を返していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
string の中身を NUL 文字終端された表現で返します。ポインタは string オブジェクトの内部バッファを指し、バッファのコピーを指すわけではありません。 PyString_FromStringAndSize(NULL, size) を使って生成した文字列でない限り、バッファ内のデータはいかなる変更もしてはなりません。この文字列をデアロケートしてはなりません。 string が Unicode オブジェクトの場合、この関数は string のデフォルトエンコーディング版を計算し、デフォルトエンコーディング版に対して操作を行います。 string が文字列オブジェクトですらない場合、 PyString_AsString() は NULL を返して TypeError を送出します。
PyString_AsString() をマクロで実装したもので、エラーチェックを行いません。文字列オブジェクトだけをサポートします; Unicode オブジェクトを渡してはなりません。
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 * を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します; 呼び出し側は新たな参照を所有することになります。 string の以前の値に対する参照は盗み取られます。新たな文字列を生成できなければ、 string に対する古い参照は無視され、 *string の値は NULL に設定されます; その際、適切な例外情報が設定されます。
新しい文字列オブジェクトを *string に作成し、 newpart の内容を string に追加します。こちらのバージョンの関数は newpart への参照をデクリメントします。
“変更不能” である文字列オブジェクトをサイズ変更する手段です。新たな文字列オブジェクトを作成するときにのみ使用してください; 文字列がすでにコードの他の部分で使われているかもしれない場合には、この関数を使ってはなりません。入力する文字列オブジェクトの参照カウントが 1 でない場合、この関数を呼び出すとエラーになります。左側値には、既存の文字列オブジェクトのアドレスを渡し (このアドレスには書き込み操作が起きるかもしれません)、新たなサイズを指定します。成功した場合、 *string はサイズ変更された文字列オブジェクトを保持し、 0 が返されます; *string の値は、入力したときの値と異なっているかもしれません。文字列の再アロケーションに失敗した場合、 *string に入っていた元の文字列オブジェクトを解放し、 *string を NULL にセットし、メモリ例外をセットし、 -1 を返します。
バージョン 2.5 で変更: この関数は以前は newsize の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
新たな文字列オブジェクトを format と args から生成します。 format % args と似た働きです。引数 args はタプルでなければなりません。
引数 *string をインプレースで隔離 (intern) します。引数は Python 文字列オブジェクトを指すポインタへのアドレスでなくてはなりません。 *string と等しい、すでに隔離済みの文字列が存在する場合、そのオブジェクトを *string に設定します (かつ、元の文字列オブジェクトの参照カウントをデクリメントし、すでに隔離済みの文字列オブジェクトの参照カウントをインクリメントします)。 (補足: 参照カウントについては沢山説明して来ましtが、この関数は参照カウント中立 (reference-count-neutral) と考えてください; この関数では、関数の呼び出し後にオブジェクトに対して参照の所有権を持てるのは、関数を呼び出す前にすでに所有権を持っていた場合に限ります。)
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
PyString_FromString() と PyString_InternInPlace() を組み合わせたもので、隔離済みの新たな文字列オブジェクトを返すか、同じ値を持つすでに隔離済みの文字列オブジェクトに対する新たな (“所有権を得た”) 参照を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
size からなるエンコード済みのバッファ s を encoding の名前で登録されている codec に渡してデコードし、オブジェクトを生成します。 encoding および errors は組み込み関数 unicode() に与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
文字列オブジェクトを encoding の名前で登録されている codec に渡してデコードし、Python オブジェクトを返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
size で指定されたサイズの char バッファを encoding の名前で登録されている codec に渡してエンコードし、 Python オブジェクトを返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。
バージョン 2.5 で変更: この関数は以前は size の型に int を利用していました。 この変更により、 64bit システムを正しくサポートするには修正が必要になります。
エンコード名 encoding で登録された codec を使って文字列オブジェクトをエンコードし、その結果を Python オブジェクトとして返します。 encoding および errors は文字列型の encode() メソッドに与える同名のパラメタと同じ意味を持ちます。使用する codec の検索は、 Python の codec レジストリを使って行います。codec が例外を送出した場合には NULL を返します。
ノート
この関数は 3.x では利用できず、 PyBytes エイリアスもありません。