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

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

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'"
  です。

* When "rv < 0", the output conversion failed and "str[size-1]" is
  "'\0'" in this case too, but the rest of *str* is undefined. The
  exact cause of the error depends on the underlying platform.

以下の関数は 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)*.

   Added in version 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)*.

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

   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_INFINITY" (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" を返します。

   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* can be zero or more of the following values or-ed together:

   Py_DTSF_SIGN

      Always precede the returned string with a sign character, even
      if *val* is non-negative.

   Py_DTSF_ADD_DOT_0

      Ensure that the returned string will not look like an integer.

   Py_DTSF_ALT

      Apply "alternate" formatting rules. See the documentation for
      the "PyOS_snprintf()" "'#'" specifier for details.

   Py_DTSF_NO_NEG_0

      Negative zero is converted to positive zero.

      Added in version 3.11.

   If *ptype* is non-"NULL", then the value it points to will be set
   to one of the following constants depending on the type of *val*:

   +----------------------------------------------------+----------------------------------------------------+
   | **ptype*                                           | type of *val*                                      |
   |====================================================|====================================================|
   | Py_DTST_FINITE                                     | finite number                                      |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_INFINITE                                   | infinite number                                    |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_NAN                                        | not a number                                       |
   +----------------------------------------------------+----------------------------------------------------+

   戻り値は変換後の文字列が格納された *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.*

   Case insensitive comparison of strings. These functions work almost
   identically to "strcmp()" and "strncmp()" (respectively), except
   that they ignore the case of ASCII characters.

   Return "0" if the strings are equal, a negative value if *str1*
   sorts lexicographically before *str2*, or a positive value if it
   sorts after.

   In the *str1* or *str2* arguments, a NUL byte marks the end of the
   string. For "PyOS_mystrnicmp()", the *size* argument gives the
   maximum size of the string, as if NUL was present at the index
   given by *size*.

   These functions do not use the locale.

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

   Case insensitive comparison of strings.

   On Windows, these are aliases of "stricmp()" and "strnicmp()",
   respectively.

   On other platforms, they are aliases of "PyOS_mystricmp()" and
   "PyOS_mystrnicmp()", respectively.


Character classification and conversion
***************************************

The following macros provide locale-independent (unlike the C standard
library "ctype.h") character classification and conversion. The
argument must be a signed or unsigned char.

Py_ISALNUM(c)

   Return true if the character *c* is an alphanumeric character.

Py_ISALPHA(c)

   Return true if the character *c* is an alphabetic character ("a-z"
   and "A-Z").

Py_ISDIGIT(c)

   Return true if the character *c* is a decimal digit ("0-9").

Py_ISLOWER(c)

   Return true if the character *c* is a lowercase ASCII letter
   ("a-z").

Py_ISUPPER(c)

   Return true if the character *c* is an uppercase ASCII letter
   ("A-Z").

Py_ISSPACE(c)

   Return true if the character *c* is a whitespace character (space,
   tab, carriage return, newline, vertical tab, or form feed).

Py_ISXDIGIT(c)

   Return true if the character *c* is a hexadecimal digit ("0-9",
   "a-f", and "A-F").

Py_TOLOWER(c)

   Return the lowercase equivalent of the character *c*.

Py_TOUPPER(c)

   Return the uppercase equivalent of the character *c*.
