字串轉換與格式化

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

intPyOS_snprintf(char*str,size_tsize,constchar*format,...)
為穩定 ABI 的一部分.

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

intPyOS_vsnprintf(char*str,size_tsize,constchar*format,va_listva)
為穩定 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。請注意，這表示沒有與 C99n=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) 的字串到數字的轉換。

unsignedlongPyOS_strtoul(constchar*str,char**ptr,intbase)
為穩定 ABI 的一部分.

Convert the initial part of the string instr to anunsignedlong value according to the givenbase, which must be between2 and36 inclusive, or be the special value0.

Leading white space and case of characters are ignored. Ifbase is zeroit looks for a leading0b,0o or0x to tell which base. Ifthese are absent it defaults to10. Base must be 0 or between 2 and 36(inclusive). Ifptr is non-NULL it will contain a pointer to theend of the scan.

If the converted value falls out of range of corresponding return type,range error occurs (errno is set toERANGE) andULONG_MAX is returned. If no conversion can be performed,0is returned.

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

在 3.2 版被加入.

longPyOS_strtol(constchar*str,char**ptr,intbase)
為穩定 ABI 的一部分.

Convert the initial part of the string instr to anlong valueaccording to the givenbase, which must be between2 and36inclusive, or be the special value0.

Same asPyOS_strtoul(), but return along value insteadandLONG_MAX on overflows.

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

在 3.2 版被加入.

doublePyOS_string_to_double(constchar*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(doubleval,charformat_code,intprecision,intflags,int*ptype)
為穩定 ABI 的一部分.

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

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 版被加入.

intPyOS_stricmp(constchar*s1,constchar*s2)

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

intPyOS_strnicmp(constchar*s1,constchar*s2,Py_ssize_tsize)

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