文字列の変換と書式化

数値変換と、書式化文字列出力のための関数群。

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

書式化文字列 format と追加の引数から、 size バイトを超えない文字列を str に出力します。 Unix man page の snprintf(2) を参照してください。

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

書式化文字列 format と可変長引数リスト va から、 size バイトを超えない文字列を str に出力します。 Unix man page の vsnprintf(2) を参照してください。

PyOS_snprintf() と PyOS_vsnprintf() は標準Cライブラリの snprintf() と vsnprintf() 関数をラップします。これらの関数の目的は、C標準ライブラリが保証していないコーナーケースでの動作を保証することです。

これらのラッパ関数は、戻るときに str*[*size-1] が常に '\0' であることを保証します。 (str の末尾の '\0' を含めて) size バイト以上を書き込みません。両関数とも str != NULL, size > 0, format != NULL を要求します。

もし vsnprintf() のないプラットフォームで、切り捨てを避けるために必要なバッファサイズが size を512バイトより大きく超過していれば、 Python は Py_FatalError で abort します。

これらの関数の戻り値 (以下では rv とします) は以下の意味を持ちます:

• 0 <= rv < size のとき、変換出力は成功して、(最後の str*[*rv] にある '\0' を除いて) rv 文字が str に出力された。
• rv >= size のとき、変換出力は切り詰められており、成功するためには rv + 1 バイトが必要だったことを示します。str*[*size-1] は '\0' です。
• rv < 0 のときは、何か悪いことが起こった時です。この場合でも str*[*size-1] は '\0' ですが、str のそれ以外の部分は未定義です。エラーの正確な原因はプラットフォーム依存です。

以下の関数は locale 非依存な文字列から数値への変換を行ないます。

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

文字列 s を double に変換します。失敗したときは Python の例外を発生させます。受け入れられる文字列は、 Python の float() コンストラクタが受け付ける文字列に準拠しますが、 s の先頭と末尾に空白文字があってはならないという部分が異なります。この変換は現在のロケールに依存しません。

endptr が NULL の場合、変換は文字列全体に対して行われます。文字列が正しい浮動小数点数の表現になっていない場合は -1.0 を返して ValueError を発生させます。

endptr が NULL で無い場合、文字列を可能な範囲で変換して、*endptr に最初の変換されなかった文字へのポインタを格納します。文字列の先頭に正しい浮動小数点数の表現が無かった場合、*endptr を文字列の先頭に設定して、ValueError を発生させ、-1.0 を返します。

s が float に格納し切れないほど大きい値を表現していた場合、(例えば、"1e500" は多くのプラットフォームで表現できません) overflow_exception が NULL なら Py_HUGE_VAL に適切な符号を付けて返します。他の場合は overflow_exception は Python の例外オブジェクトへのポインタでなければならず、その例外を発生させて -1.0 を返します。どちらの場合でも、*endptr には変換された値の直後の最初の文字へのポインタが設定されます。

それ以外のエラーが変換中に発生した場合(例えば out-of-memory エラー)、適切な Python の例外を設定して -1.0 を返します。

バージョン 2.7 で追加.

double PyOS_ascii_strtod(const char *nptr, char **endptr)

文字列を double へ変換します。この関数は、C locale における C 標準の strtod() と同じように動作します。スレッドセーフのために、この関数は現在の locale を変更せずに実装されています。

PyOS_ascii_strtod() は通常、設定ファイルを読み込むときや、ロケール独立な非ユーザーからの入力を読み込むときに使われるべきです。

詳細は Unix man page の strtod(2) を参照してください。

バージョン 2.4 で追加.

バージョン 2.7 で撤廃: 代わりに PyOS_string_to_double() を使ってください。

char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)

double を '.' を小数点記号に利用して文字列に変換します。 format は数値のフォーマットを指定する printf() スタイルの文字列です。利用できる変換文字は 'e', 'E', 'f', 'F', 'g', 'G' です。

戻り値は、変換された文字列が格納された buffer へのポインタか、失敗した場合は NULL です。

バージョン 2.4 で追加.

バージョン 2.7 で撤廃: この関数は Python 2.7 と 3.1 では削除されました。代わりに PyOS_double_to_string() を使ってください。

char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

double val を指定された format_code, precision, flags に基づいて文字列に変換します。

format_code は 'e', 'E', 'f', 'F', 'g', 'G', 'r' のどれかでなければなりません。 'r' の場合、 precision は 0 でなければならず、無視されます。 'r' フォーマットコードは標準の repr() フォーマットを指定しています。

flags は 0 か、Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, Py_DTSF_ALT かこれらの or を取ったものです:

• Py_DTSF_SIGN は、val が負で無いときも常に符号文字を先頭につけることを意味します。
• Py_DTSF_ADD_DOT_0 は文字列が整数のように見えないことを保証します。
• Py_DTSF_ALT は "alternate" フォーマットルールを適用することを意味します。詳細は PyOS_snprintf() の '#' 指定を参照してください。

ptype が NULL で無い場合、val が有限数、無限数、NaNのどれかに合わせて、Py_DTST_FINITE, Py_DTST_INFINITE, Py_DTST_NAN のいずれかに設定されます。

戻り値は変換後の文字列が格納された buffer へのポインタか、変換が失敗した場合は NULL です。呼び出し側は、返された文字列を PyMem_Free() を使って解放する責任があります。

バージョン 2.7 で追加.

double PyOS_ascii_atof(const char *nptr)

文字列を、 locale 非依存な方法で double へ変換します。

詳細は Unix man page の atof(2) を参照してください。

バージョン 2.4 で追加.

バージョン 3.1 で撤廃: 代わりに PyOS_string_to_double() を使ってください。

char* PyOS_stricmp(char *s1, char *s2)

大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strcmp() と同じ動作をします。

バージョン 2.6 で追加.

char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t  size)

大文字/小文字を区別しない文字列比較。大文字/小文字を無視する以外は、 strncmp() と同じ動作をします。

バージョン 2.6 で追加.