字符串轉換與格式化?

用于數字轉換和格式化字符串輸出的函數

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

根據格式字符串 format 和額外參數，輸出不超過 size 字節到 str 。請參見Unix手冊頁 snprintf(2) 。

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

根據格式字符串 format 和 變量參數列表 va ，不能輸出超過 size 字節到 str 。請參見Unix手冊頁 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.

包裝器確保 str*[*size-1] 在返回時始終是 '\0' 。它們從不寫入超過 size 字節（包括結尾的 '\0' ）到字符串。兩函數都需要滿足 str != NULL , size > 0 和 format != NULL 。

如果平臺沒有 vsnprintf() 而且緩沖區大小需要避免截斷超出 size 512 字節以上，Python 會以一個 Py_FatalError() 來中止。

這些函數的返回值（ rv ）應按照以下規則被解釋：

  • 當 0 <= rv < size ，輸出轉換成功而且 rv 個字符被寫入 str （不包含末尾 str*[*rv] 的 '\0' 字節）

  • 當 rv >= size ，輸出轉換被截斷并且成功需要一個帶有 rv + 1 字節的緩沖區。在這種情況下， str*[*size-1] 的值是 '\0' 。

  • 當 rv < 0 ，會發生一些不好的事情。 在這種情況下， str*[*size-1] 的值也是 '\0' ， 但是 str 的其余部分未被定義。錯誤的確切原因取決于底層平臺。

以下函數提供與語言環境無關的字符串到數字轉換。

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

將字符串 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)?

轉換 double val 為一個使用 format_code， precision 和 flags 的字符串

格式碼 必須是以下其中之一, 'e', 'E', 'f', 'F', 'g', 'G' 或者 'r'。對于 'r' , 提供的 精度 必須是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 表示應用 "替代的" 格式化規則。 相關細節請參閱 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() 的工作方式相同，只是它忽略了大小寫。