字符串转换和格式化

用于数字转换和格式化字符串输出的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 != NULLsize > 0format != 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不得包含前导或尾随空格。转换与当前语言环境无关。

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

如果 endptr 不是NULL,请转换尽可能多的字符串,并将*endptr设置为指向第一个未转换的字符。如果字符串的起始段都不是浮点数的有效表示形式,则将*endptr设置为指向字符串的开头,引发 ValueError 并返回-1.0

如果s表示的值太大而无法存储在浮点数中(例如"1e500"在许多平台上都是这样的字符串),则如果overflow_exceptionNULL则返回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。