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

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

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

* 當 "rv < 0" 時，代表輸出的轉換失敗，且在這種情況下 "str[size-1]" 也
  是 "'\0'"，但 *str* 的其餘部分未定義。錯誤的確切原因取決於底層平台。

以下函式提供與區域設定無關 (locale-independent) 的字串到數字的轉換。

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

   在 3.2 版被加入.

long PyOS_strtol(const char *str, char **ptr, int base)
    * 為 穩定 ABI 的一部分.*

   將字串 "str" 的初始部分根據給定的 "base" 轉換為 long 值，底 必須介
   於 "2" 到 "36" （包含）之間，或為特殊值 "0"。

   與 "PyOS_strtoul()" 相同，但回傳 long 值，並在溢位時回傳 "LONG_MAX"
   。

   也請見 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_INFINITY"（會帶有適當的符號）並且不設定任何例外。否則，
   "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* 可以是零個或多個以下的值被聯集在一起：

   Py_DTSF_SIGN

      總是在回傳的字串前面加上正負號字元 (sign character)，即使 *val*
      非負數。

   Py_DTSF_ADD_DOT_0

      確保回傳的字串看起來不會像整數。

   Py_DTSF_ALT

      套用「備用的 (alternate)」格式化規則。有關詳細資訊，請參閱
      "PyOS_snprintf()" "'#'" 的文件。

   Py_DTSF_NO_NEG_0

      負零會被轉換為正零。

      在 3.11 版被加入.

   如果 *ptype* 是非 "NULL"，那麼它指向的值將根據 *val* 的類型被設定為
   以下常數之一。

   +----------------------------------------------------+----------------------------------------------------+
   | **ptype*                                           | *val* 的類型                                       |
   |====================================================|====================================================|
   | Py_DTST_FINITE                                     | 有限數                                             |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_INFINITE                                   | 無限數                                             |
   +----------------------------------------------------+----------------------------------------------------+
   | Py_DTST_NAN                                        | 非數字                                             |
   +----------------------------------------------------+----------------------------------------------------+

   回傳值是指向 *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 的一部分.*

   不區分大小寫的字串比較。函式的作用方式幾乎與 "strcmp()" 和
   "strncmp()" 相同，只是它們忽略大小寫。

   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)

   不區分大小寫的字串比較。

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