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

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
    * Part of the Stable ABI.*

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

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
    * Part of the Stable ABI.*

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

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

The wrappers ensure that "str[size-1]" is always "'\0'" upon return.
They never write more than *size* bytes (including the trailing
"'\0'") into str. Both functions require that "str != NULL", "size >
0", "format != NULL" and "size < INT_MAX". Note that this means there
is no equivalent to the C99 "n = snprintf(NULL, 0, ...)" which would
determine the necessary buffer size.

これらの関数の戻り値 (以下では *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)
    * Part of the Stable ABI.*

   文字列 "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" を返します。

   バージョン 3.1 で追加.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
    * Part of the Stable ABI.*

   "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()" を使って解放する責任があります。

   バージョン 3.1 で追加.

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

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

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

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