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不能有前导或尾随空格。转换与当前语言环境无关。

如果endptr是NULL，则转换整个字符串。如果字符串不是浮点数的有效表示，则引发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_SIGN，Py_DTSF_ADD_DOT_0或Py_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_FINITE，Py_DTST_INFINITE或Py_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()，除了它忽略了这种情况。