字串轉換和格式化¶
用於數字轉換和格式化字串輸出的函式。
-
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()。它們旨在保證在標準 C 函式無法保證的極端情況下的行為一致性。
這些封裝函式確保返回時 str[size-1] 總是 '\0'。它們絕不會寫入超過 size 位元組（包括末尾的 '\0'）到 str 中。兩個函式都要求 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 的其餘部分是未定義的。錯誤的具體原因取決於底層平臺。
以下函式提供了與語言環境無關的字串到數字轉換。
-
unsigned long PyOS_strtoul(const char *str, char **ptr, int base)¶
- 作為 穩定 ABI 的一部分。
根據給定的
base，將str中的字串的初始部分轉換為 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 的一部分。
根據給定的
base，將str中的字串的初始部分轉換為 long 值，base必須在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、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()相同，只是它忽略了大小寫。