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

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
    * 次に属します: Stable ABI.*

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

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
    * 次に属します: 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 非依存な文字列から数値への変換を行ないます。

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
    * 次に属します: Stable ABI.*

   Convert the initial part of the string in "str" to an unsigned long
   value according to the given "base", which must be between "2" and
   "36" inclusive, or be the special value "0".

   Leading white space and case of characters are ignored.  If "base"
   is zero it looks for a leading "0b", "0o" or "0x" to tell which
   base.  If these are absent it defaults to "10".  Base must be 0 or
   between 2 and 36 (inclusive).  If "ptr" is non-"NULL" it will
   contain a pointer to the end of the scan.

   If the converted value falls out of range of corresponding return
   type, range error occurs ("errno" is set to "ERANGE") and
   "ULONG_MAX" is returned.  If no conversion can be performed, "0" is
   returned.

   See also the Unix man page *strtoul(3)*.

   バージョン 3.2 で追加.

long PyOS_strtol(const char *str, char **ptr, int base)
    * 次に属します: Stable ABI.*

   Convert the initial part of the string in "str" to an long value
   according to the given "base", which must be between "2" and "36"
   inclusive, or be the special value "0".

   Same as "PyOS_strtoul()", but return a long value instead and
   "LONG_MAX" on overflows.

   See also the Unix man page *strtol(3)*.

   バージョン 3.2 で追加.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
    * 次に属します: Stable ABI.*

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

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

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

   If "s" represents a value that is too large to store in a float
   (for example, ""1e500"" is such a string on many platforms) then if
   "overflow_exception" is "NULL" return "Py_HUGE_VAL" (with an
   appropriate sign) and don't set any exception.  Otherwise,
   "overflow_exception" must point to a Python exception object; raise
   that exception and return "-1.0".  In both cases, set "*endptr" to
   point to the first character after the converted value.

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

   バージョン 3.1 で追加.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
    * 次に属します: 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)

   Case insensitive comparison of strings. The function works almost
   identically to "strcmp()" except that it ignores the case.

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

   Case insensitive comparison of strings. The function works almost
   identically to "strncmp()" except that it ignores the case.
