字符串转换和格式化

用于数字转换和格式化字符串输出的Function。

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

  • 根据格式字符串* format 和额外的参数，向 str 输出不超过 size 个字节。请参见 Unix 手册页 snprintf(2) *。

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

  • 根据格式字符串* format 和变量参数列表 va ，向 str 输出不超过 size 个字节。 Unix 手册页 vsnprintf(2) *。

PyOS_snprintf()和PyOS_vsnprintf()包装标准 C 库函数snprintf()和vsnprintf()。它们的目的是保证在极端情况下的一致行为，而标准 C 函数则不这样做。

包装器确保返回时* str * [* size * -1]始终为'\0'。他们向 str 中写入的字节数绝不超过* size *个字节(包括结尾的'\0')。这两个函数都要求str != NULL，size > 0和format != NULL。

如果平台没有vsnprintf()，并且避免截断所需的缓冲区大小超过* size *超过 512 个字节，则 Python 会以Py_FatalError()中止。

这些函数的返回值(* rv *)应该解释如下：

• 当0 <= rv < size时，输出转换成功，并且* rv 字符被写入 str (不包括 str * [* rv *]的尾随'\0'字节)。

• 当rv >= size时，输出转换被截断，并且需要rv + 1字节的缓冲区才能成功。在这种情况下，* str * [* size * -1]为'\0'。

• rv < 0时，“发生了不好的事情”。在这种情况下，* str * [* size * -1]也是'\0'，但是其余的* str *是未定义的。错误的确切原因取决于基础平台。

以下函数提供了与语言环境无关的字符串到数字的转换。

• 双精度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。

如果s表示的值太大而无法存储在浮点数中(例如"1e500"在许多平台上都是这样的字符串)，则如果overflow_exception是NULL则返回Py_HUGE_VAL(带有适当的符号)并且不要设置任何异常。否则，overflow_exception必须指向 Python 异常对象。引发该异常并返回-1.0。在两种情况下，都将*endptr设置为指向转换后的值后的第一个字符。

如果在转换过程中发生任何其他错误(例如，内存不足错误)，请设置适当的 Python 异常并返回-1.0。

3.1 版中的新Function。

• char * PyOS_double_to_string(double * val *，char * format_code *，int * precision *，int * flags *，int ** ptype *)
  • 使用提供的* 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的零个或多个，或-ed 在一起：

• 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。调用者负责pass调用PyMem_Free()释放返回的字符串。

3.1 版中的新Function。

• int PyOS_stricmp(const char *s1 ，const char s2 *)

  • 字符串的大小写不敏感比较。该Function与strcmp()几乎相同，除了它忽略大小写。

• int PyOS_strnicmp(const char *s1 ，const char s2 *，Py_ssize_t * size *)

  • 字符串的大小写不敏感比较。该Function与strncmp()几乎相同，除了它忽略大小写。