字符串转换和格式化

用于数字转换和格式化字符串输出的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'。它们写入的字节数绝不超过* size *个字节(包括在 str 中尾随'\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。

2.7 版的新Function。

• double PyOS_ascii_strtod(const char *nptr ，char * endptr *)
  • 将字符串转换为double。该函数的行为类似于标准 C 函数strtod()在 C 语言环境中的行为。这样做不会更改当前语言环境，因为那不是线程安全的。

PyOS_ascii_strtod()通常应用于读取配置文件或其他与区域设置无关的非用户 Importing。

有关详细信息，请参见 Unix 手册页* strtod(2)*。

2.4 版的新Function。

从 2.7 版开始不推荐使用：改为使用PyOS_string_to_double()。

• char * PyOS_ascii_formatd(char **buffer ，size_t * buf_len ，const char format *，double * d *)
  • 使用'.'作为小数点分隔符将double转换为字符串。 * format *是printf()样式的格式字符串，用于指定数字格式。允许的转换字符为'e'，'E'，'f'，'F'，'g'和'G'。

返回值是带有转换后的字符串的* buffer *指针，如果转换失败，则返回 NULL。

2.4 版的新Function。

从 2.7 版开始不推荐使用：此Function在 Python 2.7 和 3.1 中已删除。请改用PyOS_double_to_string()。

• 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'，提供的精度*必须为0并被忽略。 'r'格式代码指定标准的repr()格式。

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

2.7 版的新Function。

• 双PyOS_ascii_atof(const char ** nptr *)
  • 以与语言环境无关的方式将字符串转换为double。

有关详细信息，请参见 Unix 手册页* atof(2)*。

2.4 版的新Function。

从版本 3.1 开始不推荐使用：改为使用PyOS_string_to_double()。

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

2.6 版的新Function。

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

2.6 版的新Function。