字串轉換和格式化¶
用於數字轉換和格式化字串輸出的函式。
-
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'。它們永遠不會向 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* 的其餘部分是未定義的。錯誤的具體原因取決於底層平臺。
以下函式提供了與區域設定無關的字串到數字的轉換。
-
unsigned long PyOS_strtoul(const char *str, char **ptr, int base)¶
- 屬於 穩定 ABI 的一部分。
根據給定的 *base* 將
str中的字串的初始部分轉換為 unsigned long 值，該值必須在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 值，該值必須在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_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)¶
- 屬於 穩定 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()幾乎相同，只是它忽略大小寫。