String conversion and formatting — Python 3.11.15 documentation
Description: Functions for number conversion and formatted string output. PyOS_snprintf() and PyOS_vsnprintf() wrap the Standard C library functions snprintf() and vsnprintf(). Their purpose is to guarantee con...

# String conversion and formatting

Functions for number conversion and formatted string output.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)
  Part of the Stable ABI.

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

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
  Part of the Stable ABI.

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

`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`, `format != NULL` and `size < INT_MAX`. Note that this means there is no equivalent to the C99 `n = snprintf(NULL, 0, ...)` which would determine the necessary buffer size.

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.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)
  Part of the Stable ABI.

  Convert the initial part of the string in `str` to an unsigned long value according to the given `base`, which must be between `2` and `36` inclusive, or be the special value `0`.

  Leading white space and case of characters are ignored. If `base` is zero it looks for a leading `0b`, `0o` or `0x` to tell which base. If these are absent it defaults to `10`. Base must be 0 or between 2 and 36 (inclusive). If `ptr` is non-`NULL` it will contain a pointer to the end of the scan.

  If the converted value falls out of range of corresponding return type, range error occurs (`errno` is set to `ERANGE`) and `ULONG_MAX` is returned. If no conversion can be performed, `0` is returned.

  See also the Unix man page strtoul(3).

  New in version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)
  Part of the Stable ABI.

  Convert the initial part of the string in `str` to an long value according to the given `base`, which must be between `2` and `36` inclusive, or be the special value `0`.

  Same as `PyOS_strtoul()`, but return a long value instead and `LONG_MAX` on overflows.

  See also the Unix man page strtol(3).

  New in version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
  Part of the Stable ABI.

  Convert a string `s` to a double, raising a Python exception on failure. The set of accepted strings corresponds to the set of strings accepted by Python’s `float()` constructor, except that `s` must not have leading or trailing whitespace. The conversion is independent of the current locale.

  If `endptr` is `NULL`, convert the whole string. Raise `ValueError` and return `-1.0` if the string is not a valid representation of a floating-point number.

  If endptr is not `NULL`, convert as much of the string as possible and set `*endptr` to point to the first unconverted character. If no initial segment of the string is the valid representation of a floating-point number, set `*endptr` to point to the beginning of the string, raise ValueError, and return `-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. Otherwise, `overflow_exception` must point to a Python exception object; raise that exception and return `-1.0`. In both cases, set `*endptr` to point to the first character after the converted value.

  If any other error occurs during the conversion (for example an out-of-memory error), set the appropriate Python exception and return `-1.0`.

  New in version 3.1.

char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
  Part of the Stable ABI.

  Convert a double val to a string using supplied format_code, precision, and flags.

  format_code must be one of `'e'`, `'E'`, `'f'`, `'F'`, `'g'`, `'G'` or `'r'`. For `'r'`, the supplied precision must be 0 and is ignored. The `'r'` format code specifies the standard `repr()` format.

  flags can be zero or more of the values `Py_DTSF_SIGN`, `Py_DTSF_ADD_DOT_0`, or `Py_DTSF_ALT`, or-ed together:

  - `Py_DTSF_SIGN` means to always precede the returned string with a sign character, even if val is non-negative.

  - `Py_DTSF_ADD_DOT_0` means to ensure that the returned string will not look like an integer.

  - `Py_DTSF_ALT` means to apply “alternate” formatting rules. See the documentation for the `PyOS_snprintf()` `'#'` specifier for details.

  If ptype is non-`NULL`, then the value it points to will be set to one of `Py_DTST_FINITE`, `Py_DTST_INFINITE`, or `Py_DTST_NAN`, signifying that val is a finite number, an infinite number, or not a number, respectively.

  The return value is a pointer to buffer with the converted string or `NULL` if the conversion failed. The caller is responsible for freeing the returned string by calling `PyMem_Free()`.

  New in version 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

  Case insensitive comparison of strings. The function works almost identically to `strcmp()` except that it ignores the case.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

  Case insensitive comparison of strings. The function works almost identically to `strncmp()` except that it ignores the case.