文字列の変換と書式化
********************

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

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 で追加.
