字串轉換與格式化

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

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 != NULLsize > 0format != NULLsize < 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 的一部分.

根据给定的 basestr 中字符串的初始部分转换为 unsigned long 值,该值必须在 236 的开区间内,或者为特殊值 0

空白前缀和字符大小写将被忽略。 如果 base 为零则会查找 0b0o0x 前缀以确定基数。 如果没有则默认基数为 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 的一部分.

根据给定的 basestr 中字符串的初始部分转换为 long 值,该值必须在 236 的开区间内,或者为特殊值 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 不得有前導或尾隨的空格。轉換與目前區域設定無關。

如果 endptrNULL,則轉換整個字串。如果字串不是浮點數的有效表示,則引發 ValueError 並回傳 -1.0

如果 endptr 不是 NULL,則盡可能轉換字串,並將 *endptr 設定為指向第一個未轉換的字元。如果字串的初始片段都不是浮點數的有效表示,則設定 *endptr 指向字串的開頭,引發 ValueError 並回傳 -1.0

如果 s 表示的值太大而無法儲存在浮點數中(例如 "1e500" 在許多平台上都是這樣的字串),如果 overflow_exceptionNULL 則回傳 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_codeprecisionflagsdouble val 轉換為字串。

format_code 必須是 'e''E''f''F''g''G''r' 其中之一。對於 'r',提供的 precision 必須為 0 並會被忽略。'r' 格式碼指定標準 repr() 格式。

flags 可以是零個或多個值 Py_DTSF_SIGNPy_DTSF_ADD_DOT_0Py_DTSF_ALT,會被聯集在一起:

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

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

  • Py_DTSF_ALT 代表要套用「備用的 (alternate)」格式化規則。有關詳細資訊,請參閱 PyOS_snprintf() '#' 的文件。

如果 ptype 是非 NULL,那麼它指向的值將被設定為 Py_DTST_FINITEPy_DTST_INFINITEPy_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() 相同,只是它忽略大小寫。