字串轉換與格式化¶
數字轉換函數和被格式化的字串輸出。
-
int
PyOS_snprintf
(char *str, size_t size, const char *format, ...)¶ Output not more than size bytes to str according to the format string format and the extra arguments. See the Unix man page snprintf(2).
-
int
PyOS_vsnprintf
(char *str, size_t size, const char *format, va_list va)¶ Output not more than size bytes to str according to the format string format and the variable argument list va. Unix man page 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.
The wrappers ensure that str*[*size-1] is always '\0'
upon return. They
never write more than size bytes (including the trailing '\0'
) into str.
Both functions require that str != NULL
, size > 0
and format !=
NULL
.
如果平台没有 vsnprintf()
而且缓冲区大小需要避免截断超出 size 512 字节以上,Python 会以一个 Py_FatalError()
来中止。
當回傳值 (rv) 給這些函數應該被編譯如下:
When
0 <= rv < size
, the output conversion was successful and rv characters were written to str (excluding the trailing'\0'
byte at str*[*rv]).When
rv >= size
, the output conversion was truncated and a buffer withrv + 1
bytes would have been needed to succeed. str*[*size-1] is'\0'
in this case.When
rv < 0
, "something bad happened." str*[*size-1] is'\0'
in this case too, but the rest of str is undefined. The exact cause of the error depends on the underlying platform.
The following functions provide locale-independent string to number conversions.
-
double
PyOS_string_to_double
(const char *s, char **endptr, PyObject *overflow_exception)¶ Convert a string
s
to adouble
, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python'sfloat()
constructor, except thats
must not have leading or trailing whitespace. The conversion is independent of the current locale.If
endptr
isNULL
, convert the whole string. RaiseValueError
and return-1.0
if the string is not a valid representation of a floating-point number.If endptr is not
NULL
, convert as much of the string as possible and set*endptr
to point to the first unconverted character. If no initial segment of the string is the valid representation of a floating-point number, set*endptr
to point to the beginning of the string, raise ValueError, and return-1.0
.If
s
represents a value that is too large to store in a float (for example,"1e500"
is such a string on many platforms) then ifoverflow_exception
isNULL
returnPy_HUGE_VAL
(with an appropriate sign) and don't set any exception. Otherwise,overflow_exception
must point to a Python exception object; raise that exception and return-1.0
. In both cases, set*endptr
to point to the first character after the converted value.If any other error occurs during the conversion (for example an out-of-memory error), set the appropriate Python exception and return
-1.0
.3.1 版新加入.
-
char*
PyOS_double_to_string
(double val, char format_code, int precision, int flags, int *ptype)¶ Convert a
double
val to a string using supplied format_code, precision, and flags.format_code must be one of
'e'
,'E'
,'f'
,'F'
,'g'
,'G'
or'r'
. For'r'
, the supplied precision must be 0 and is ignored. The'r'
format code specifies the standardrepr()
format.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)¶ Case insensitive comparison of strings. The function works almost identically to
strcmp()
except that it ignores the case.
-
int
PyOS_strnicmp
(const char *s1, const char *s2, Py_ssize_t size)¶ Case insensitive comparison of strings. The function works almost identically to
strncmp()
except that it ignores the case.