String conversion and formatting

数字转换和格式化字符串输出的函数。

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

根据格式字符串格式输出不超过大小字节到str和额外的参数。请参见Unix手册页snprintf(2)

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

根据格式字符串格式和可变参数列表va,输出不超过size字节到str。 Unix手册页vsnprintf(2)

PyOS_snprintf()PyOS_vsnprintf()包装标准库函数snprintf()vsnprintf()它们的目的是保证在角落情况下的一致行为,标准C功能不这样做。

包装器确保返回时str * [* size -1]始终为'\0'它们不会将超过size个字节(包括尾部'\0')写入str。Both functions require that str != NULL, size > 0 and format != NULL.

如果平台没有vsnprintf(),并且避免截断所需的缓冲区大小超过512字节超过size,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]).
  • rv > = size时,输出转换被截断,并且rv + 1字节。在这种情况下,str * [* size -1]是'\0'
  • rv 0时,“发生了一些不好的情况”。str * t4> -1]在这种情况下也是'\0',但str的其余部分是未定义的。错误的确切原因取决于底层平台。

以下函数提供与区域设置无关的字符串到数字转换。

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

将字符串s转换为double,在失败时引发Python异常。接受的字符串集合对应于Python的float()构造函数接受的字符串集合,除了s不能有前导或尾随空格。转换与当前语言环境无关。

如果endptrNULL,则转换整个字符串。如果字符串不是浮点数的有效表示,则引发ValueError并返回-1.0

如果endptr不是NULL,则尽可能多地转换字符串,并将*endptr指向第一个未转换的字符。如果没有字符串的初始段是浮点数的有效表示,请将*endptr设置为指向字符串的开头,引发ValueError,并返回-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 if overflow_exception is NULL return Py_HUGE_VAL (with an appropriate sign) and don’t set any exception. 否则,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)

使用提供的format_code精确标志double val

format_code必须是'e''E''f''F''g''G''r'对于'r',提供的精度必须为0并被忽略。'r'格式代码指定标准repr()格式。

标志可以是Py_DTSF_SIGNPy_DTSF_ADD_DOT_0Py_DTSF_ALT中的零个或多个值,

  • Py_DTSF_SIGN意味着总是在带有符号字符的返回字符串之前,即使val是非负数。
  • Py_DTSF_ADD_DOT_0 means to ensure that the returned string will not look like an integer.
  • Py_DTSF_ALT表示应用“备用”格式规则。有关详细信息,请参阅PyOS_snprintf() '#'说明符的文档。

如果ptype是非NULL,则它指向的值将被设置为Py_DTST_FINITEPy_DTST_INFINITEPy_DTST_NAN ,表示val分别是有限数字,无限数字或不是数字。

如果转换失败,则返回值是指向转换字符串的缓冲区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(),除了它忽略了这种情况。