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

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

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".

如果平台没有 "vsnprintf()" 而且缓冲区大小需要避免截断超出 *size* 512
字节以上，Python 会以一个 "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".

   3.1 版新加入.

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* 可以为零或者其他值 "Py_DTSF_SIGN", "Py_DTSF_ADD_DOT_0" 或
   "Py_DTSF_ALT" 或其组合：

   * "Py_DTSF_SIGN" 表示总是在返回的字符串前附加一个符号字符，即使
     *val* 为非负数。

   * "Py_DTSF_ADD_DOT_0" 表示确保返回的字符串看起来不像是一个整数。

   * "Py_DTSF_ALT" 表示应用 "替代的" 格式化规则。 相关细节请参阅
     "PyOS_snprintf()" "'#'" 定义文档。

   如果 *ptype* 不为 "NULL"，则它指向的值将被设为 "Py_DTST_FINITE",
   "Py_DTST_INFINITE" 或 "Py_DTST_NAN" 中的一个，分别表示 *val* 是一个
   有限数字、无限数字或非数字。

   返回值是一个指向包含转换后字符串的 *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.
