#
5.6 String conversion and formatting

Functions for number conversion and formatted string output.

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

  Output not more than size bytes to str according to the format string format and the extra arguments. See the Unix man page snprintf(2).

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

  Output not more than size bytes to str according to the format string format and the variable argument list va. Unix man page vsnprintf(2).

`PyOS_snprintf` and `PyOS_vsnprintf` wrap the Standard C library functions `snprintf()` and `vsnprintf()`. Their purpose is to guarantee consistent behavior in corner cases, which the Standard C functions do not.

The wrappers ensure that str[size-1] is always "`\0`" upon return. They never write more than size bytes (including the trailing "`\0`" into str. Both functions require that `str != NULL`, `size > 0` and `format != NULL`.

If the platform doesn't have `vsnprintf()` and the buffer size needed to avoid truncation exceeds size by more than 512 bytes, Python aborts with a Py_FatalError.

The return value (rv) for these functions should be interpreted as follows:

- When `0 <= rv < size`, the output conversion was successful and rv characters were written to str (excluding the trailing "`\0`" byte at str[rv]).

- When `rv >= size`, the output conversion was truncated and a buffer with `rv + 1` bytes would have been needed to succeed. str[size-1] is "`\0`" in this case.

- When `rv < 0`, ``something bad happened.'' str[size-1] is "`\0`" in this case too, but the rest of str is undefined. The exact cause of the error depends on the underlying platform.

The following functions provide locale-independent string to number conversions.

double `PyOS_ascii_strtod`( | const char *nptr, char **endptr)

  Convert a string to a `double`. This function behaves like the Standard C function `strtod()` does in the C locale. It does this without changing the current locale, since that would not be thread-safe.

  `PyOS_ascii_strtod` should typically be used for reading configuration files or other non-user input that should be locale independent. New in version 2.4.

  See the Unix man page strtod(2) for details.

char * `PyOS_ascii_formatd`( | char *buffer, size_t buf_len, const char *format, double d)

  Convert a `double` to a string using the "`.`" as the decimal separator. format is a `printf()`-style format string specifying the number format. Allowed conversion characters are "`e`", "`E`", "`f`", "`F`", "`g`" and "`G`".

  The return value is a pointer to buffer with the converted string or NULL if the conversion failed. New in version 2.4.

double `PyOS_ascii_atof`( | const char *nptr)

  Convert a string to a `double` in a locale-independent way. New in version 2.4.

  See the Unix man page atof(2) for details.