字串轉換與格式化
****************

數字轉換函數和被格式化的字串輸出。

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

   Output not more than *size* bytes to *str* according to the format
   string *format* and the extra arguments. See the Unix man page
   *snprintf(2)*.

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

   Output not more than *size* bytes to *str* according to the format
   string *format* and the variable argument list *va*. Unix man page
   *vsnprintf(2)*.

"PyOS_snprintf()" and "PyOS_vsnprintf()" wrap the Standard C library
functions "snprintf()" and "vsnprintf()". Their purpose is to
guarantee consistent behavior in corner cases, which the Standard C
functions do not.

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" and
"format != NULL".

If the platform doesn’t have "vsnprintf()" and the buffer size needed
to avoid truncation exceeds *size* by more than 512 bytes, Python
aborts with a *Py_FatalError*.

當回傳值 (*rv*)  給這些函數應該被編譯如下：

* When "0 <= rv < size", the output conversion was successful and
  *rv* characters were written to *str* (excluding the trailing "'\0'"
  byte at *str*[*rv*]).

* When "rv >= size", the output conversion was truncated and a
  buffer with "rv + 1" bytes would have been needed to succeed.
  *str*[*size*-1] is "'\0'" in this case.

* When "rv < 0", 「something bad happened.」 *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.

The following functions provide locale-independent string to number
conversions.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

   Convert a string "s" to a "double", raising a Python exception on
   failure.  The set of accepted strings corresponds to the set of
   strings accepted by Python’s "float()" constructor, except that "s"
   must not have leading or trailing whitespace. The conversion is
   independent of the current locale.

   If "endptr" is "NULL", convert the whole string.  Raise ValueError
   and return "-1.0" if the string is not a valid representation of a
   floating-point number.

   If endptr is not "NULL", convert as much of the string as possible
   and set "*endptr" to point to the first unconverted character.  If
   no initial segment of the string is the valid representation of a
   floating-point number, set "*endptr" to point to the beginning of
   the string, raise ValueError, and return "-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.

   If any other error occurs during the conversion (for example an
   out-of-memory error), set the appropriate Python exception and
   return "-1.0".

   2.7 版新加入.

double PyOS_ascii_strtod(const char *nptr, char **endptr)

   Convert a string to a "double". This function behaves like the
   Standard C function "strtod()" does in the C locale. It does this
   without changing the current locale, since that would not be
   thread-safe.

   "PyOS_ascii_strtod()" should typically be used for reading
   configuration files or other non-user input that should be locale
   independent.

   See the Unix man page *strtod(2)* for details.

   2.4 版新加入.

   2.7 版後已棄用: Use "PyOS_string_to_double()" instead.

char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)

   Convert a "double" to a string using the "'.'" as the decimal
   separator. *format* is a "printf()"-style format string specifying
   the number format. Allowed conversion characters are "'e'", "'E'",
   "'f'", "'F'", "'g'" and "'G'".

   The return value is a pointer to *buffer* with the converted string
   or NULL if the conversion failed.

   2.4 版新加入.

   2.7 版後已棄用: This function is removed in Python 2.7 and 3.1.
   Use "PyOS_double_to_string()" instead.

char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

   Convert a "double" *val* to a string using supplied *format_code*,
   *precision*, and *flags*.

   *format_code* must be one of "'e'", "'E'", "'f'", "'F'", "'g'",
   "'G'" or "'r'".  For "'r'", the supplied *precision* must be "0"
   and is ignored.  The "'r'" format code specifies the standard
   "repr()" format.

   *flags* can be zero or more of the values *Py_DTSF_SIGN*,
   *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:

   * *Py_DTSF_SIGN* means to always precede the returned string with
     a sign character, even if *val* is non-negative.

   * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string
     will not look like an integer.

   * *Py_DTSF_ALT* means to apply 「alternate」 formatting rules.
     See the documentation for the "PyOS_snprintf()" "'#'" specifier
     for details.

   If *ptype* is non-NULL, then the value it points to will be set to
   one of *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*,
   signifying that *val* is a finite number, an infinite number, or
   not a number, respectively.

   The return value is a pointer to *buffer* with the converted string
   or *NULL* if the conversion failed. The caller is responsible for
   freeing the returned string by calling "PyMem_Free()".

   2.7 版新加入.

double PyOS_ascii_atof(const char *nptr)

   Convert a string to a "double" in a locale-independent way.

   See the Unix man page *atof(2)* for details.

   2.4 版新加入.

   3.1 版後已棄用: Use "PyOS_string_to_double()" instead.

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

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

   2.6 版新加入.

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

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

   2.6 版新加入.
