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

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

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 的一部分.*

   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_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"、"Py_DTSF_ADD_DOT_0" 或
   "Py_DTSF_ALT"，會被聯集在一起：

   * "Py_DTSF_SIGN" 代表總是在回傳的字串前面加上符號字元，即使 *val*
     非負數。

   * "Py_DTSF_ADD_DOT_0" 代表確保回傳的字串看起來不會像整數。

   * "Py_DTSF_ALT" 代表要套用「備用的 (alternate)」格式化規則。有關詳
     細資訊，請參閱 "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)

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

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

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