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

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

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標準ライブラリが保証していないコーナーケースでの動作を保証すること
です。

これらのラッパーは、戻る時点で "str[size-1]" が必ず "'\0'" になること
を保証します。 末尾の "'\0'" を含めて、"size" バイトを超えて "str" に
書き込むことはありません。 どちらの関数も "str != NULL"、"size > 0"、
"format != NULL"、"size < INT_MAX" を必要とします。 このため、必要なバ
ッファサイズを調べる C99 の "n = snprintf(NULL, 0, ...)" に相当する操
作はできません。

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

   文字列 "str" の先頭部分を、指定された基数 "base" に従って unsigned
   long の値に変換します。 "base" は "2" 以上 "36" 以下、または特別な
   値 "0" でなければなりません。

   先頭の空白と文字の大文字・小文字の違いは無視します。 "base" がゼロ
   の場合、先頭の "0b"、"0o"、"0x" から基数を判定します。 これらがなけ
   れば "10" を使います。 基数は 0、または 2 以上 36 以下でなければな
   りません。 "ptr" が "NULL" でなければ、走査が終了した位置へのポイン
   タを格納します。

   変換した値が戻り値の型の範囲外になった場合、範囲エラーとして
   "errno" を "ERANGE" に設定し、"ULONG_MAX" を返します。 変換できなか
   った場合は "0" を返します。

   Unix マニュアルページ *strtoul(3)* も参照してください。

   Added in version 3.2.

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

   文字列 "str" の先頭部分を、指定された基数 "base" に従って long の値
   に変換します。 "base" は "2" 以上 "36" 以下、または特別な値 "0" で
   なければなりません。

   "PyOS_strtoul()" と同じですが、戻り値は long で、オーバーフロー時に
   は "LONG_MAX" を返します。

   Unix マニュアルページ *strtol(3)* も参照してください。

   Added in version 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" を返します。

   "s" が float に格納できないほど大きな値を表す場合 (多くのプラットフ
   ォームでは例えば ""1e500"")、"overflow_exception" が "NULL" なら適
   切な符号の "INFINITY" を返し、例外は設定しません。 それ以外の場合、
   "overflow_exception" は Python の例外オブジェクトを指す必要がありま
   す。 その例外を送出して "-1.0" を返します。 どちらの場合も、
   "*endptr" は変換した値の直後の文字を指すように設定されます。

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

   Added in version 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 個以上をビット OR で組み合わせて指定
   できます。

   Py_DTSF_SIGN

      "val" が負でなくても、戻り値の文字列の先頭に常に符号を付けます。

   Py_DTSF_ADD_DOT_0

      戻り値の文字列が整数のように見えないようにします。

   Py_DTSF_ALT

      「代替形式」の書式規則を適用します。 詳細は "PyOS_snprintf()" の
      "'#'" 指定子の説明を参照してください。

   Py_DTSF_NO_NEG_0

      負のゼロを正のゼロに変換します。

      Added in version 3.11.

   "ptype" が "NULL" でなければ、"val" の種類に応じて参照先を以下の定
   数のいずれかに設定します。

   +----------------------------------------------------+----------------------------------------------------+
   | "*ptype"                                           | "val" の種類                                       |
   |====================================================|====================================================|
   | Py_DTST_FINITE                                     | 有限の数値                                         |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_INFINITE                                   | 無限大                                             |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_NAN                                        | 非数                                               |
   +----------------------------------------------------+----------------------------------------------------+

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

   Added in version 3.1.

int PyOS_mystricmp(const char *str1, const char *str2)
int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)
    * 次に属します: Stable ABI.*

   大文字と小文字を区別せずに文字列を比較します。 それぞれ "strcmp()"
   と "strncmp()" とほぼ同じですが、ASCII 文字の大文字と小文字の違いを
   無視します。

   文字列が等しければ "0"、辞書順で "str1" が "str2" より前なら負の値
   、後なら正の値を返します。

   引数 "str1" と "str2" では、NUL バイトが文字列の終わりを示します。
   "PyOS_mystrnicmp()" では、"size" 引数が文字列の最大サイズを指定し、
   そのインデックスに NUL があるかのように扱います。

   これらの関数はロケールを使いません。

int PyOS_stricmp(const char *str1, const char *str2)
int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)

   大文字と小文字を区別しない文字列の比較。

   Windows では、それぞれ "stricmp()" と "strnicmp()" の別名です。

   ほかのプラットフォームでは、それぞれ "PyOS_mystricmp()" と
   "PyOS_mystrnicmp()" の別名です。


文字の分類と変換
****************

以下のマクロは、C 標準ライブラリの "ctype.h" と異なり、ロケールに依存
しない文字の分類と変換を行います。 引数は符号付きまたは符号なしの char
でなければなりません。

Py_ISALNUM(c)

   文字 "c" が英数字の場合に真を返します。

Py_ISALPHA(c)

   文字 "c" が英字 ("a-z" または "A-Z") の場合に真を返します。

Py_ISDIGIT(c)

   文字 "c" が 10 進数字 ("0-9") の場合に真を返します。

Py_ISLOWER(c)

   文字 "c" が ASCII の英小文字 ("a-z") の場合に真を返します。

Py_ISUPPER(c)

   文字 "c" が ASCII の英大文字 ("A-Z") の場合に真を返します。

Py_ISSPACE(c)

   文字 "c" が空白文字 (スペース、タブ、復帰、改行、垂直タブ、フォーム
   フィード) の場合に真を返します。

Py_ISXDIGIT(c)

   文字 "c" が 16 進数字 ("0-9"、"a-f"、"A-F") の場合に真を返します。

Py_TOLOWER(c)

   文字 "c" に対応する小文字を返します。

Py_TOUPPER(c)

   文字 "c" に対応する大文字を返します。


ビットマスク
============

以下の定数は、上記の文字分類マクロで使うビットマスクです。

PY_CTF_ALNUM
PY_CTF_ALPHA
PY_CTF_DIGIT
PY_CTF_LOWER
PY_CTF_SPACE
PY_CTF_UPPER
PY_CTF_XDIGIT

   上記の "Py_IS*" 分類マクロが内部で使う値です。 後方互換性のためだけ
   に公開しています。

   バージョン 3.15.2 で ソフト非推奨 <Soft deprecated>.
