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

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
    * 為 穩定 ABI 的一部分.*

   根據格式字串 *format* 和額外引數，輸出不超過 *size* 位元組給 *str*
   。請參閱 Unix 手冊頁面 *snprintf(3)*。

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
    * 為 穩定 ABI 的一部分.*

   根據格式字串 *format* 和變數引數串列 *va*，輸出不超過 *size* 位元組
   給 *str*。Unix 手冊頁面 *vsnprintf(3)*。

"PyOS_snprintf()" 和 "PyOS_vsnprintf()" 包裝標準 C 函式庫函式
"snprintf()" 和 "vsnprintf()"。它們的目的是確保邊角案例 (corner case)
下的行為一致，而標準 C 函式則不然。

包裝器確保回傳時 "str[size-1]" 始終為 "'\0'"。他們永遠不會在 str 中寫
入超過 *size* 位元組（包括尾隨的 "'\0'"）。這兩個函式都要求 "str !=
NULL"、"size > 0"、"format != NULL" 和 "size < INT_MAX"。請注意，這表
示沒有與 C99 "n = snprintf(NULL, 0, ...)" 等效的函式來決定必要的緩衝區
大小。

這些函式的回傳值 (*rv*) 應如下被直譯：

* 當 "0 <= rv < size" 時，輸出轉換成功，*rv* 字元被寫入 *str*（不包括
  "str[rv]" 處的尾隨 "'\0'" 位元組）。

* 當 "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-independent) 的字串到數字的轉換。

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
    * 為 穩定 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.

   也請見 Unix 手冊頁面 *strtoul(3)*。

   在 3.2 版被加入.

long PyOS_strtol(const char *str, char **ptr, int base)
    * 為 穩定 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.

   也請見 Unix 手冊頁面 *strtol(3)*。

   在 3.2 版被加入.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
    * 為 穩定 ABI 的一部分.*

   將字串 "s" 轉換為 double，失敗時引發 Python 例外。接受的字串集合對
   應於 Python 的 "float()" 建構函式接受的字串集合，但 "s" 不得有前導
   或尾隨的空格。轉換與目前區域設定無關。

   如果 "endptr" 為 "NULL"，則轉換整個字串。如果字串不是浮點數的有效表
   示，則引發 "ValueError" 並回傳 "-1.0"。

   如果 endptr 不是 "NULL"，則盡可能轉換字串，並將 "*endptr" 設定為指
   向第一個未轉換的字元。如果字串的初始片段都不是浮點數的有效表示，則
   設定 "*endptr" 指向字串的開頭，引發 ValueError 並回傳 "-1.0"。

   如果 "s" 表示的值太大而無法儲存在浮點數中（例如 ""1e500"" 在許多平
   台上都是這樣的字串），如果 "overflow_exception" 為 "NULL" 則回傳
   "Py_HUGE_VAL"（會帶有適當的符號）並且不設定任何例外。否則，
   "overflow_exception" 必須指向一個 Python 例外物件；引發該例外並回傳
   "-1.0"。在這兩種情況下，將 "*endptr" 設定為指向轉換後的值之後的第一
   個字元。

   如果轉換期間發生任何其他錯誤（例如記憶體不足的錯誤），請設定適當的
   Python 例外並回傳 "-1.0"。

   在 3.1 版被加入.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
    * 為 穩定 ABI 的一部分.*

   使用提供的 *format_code*、*precision* 和 *flags* 將 double *val* 轉
   換為字串。

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

      在 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()" 來釋放回傳的字串。

   在 3.1 版被加入.

int PyOS_mystricmp(const char *str1, const char *str2)
int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)
    * 為 穩定 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*.
