String conversion and formatting

Functions for number conversion and formatted string output.

intPyOS_snprintf(char *str, size_t size, const char *format, ...)

Output not more thansize bytes tostr according to the format stringformat and the extra arguments. See the Unix man pagesnprintf(3).

intPyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Output not more thansize bytes tostr according to the format stringformat and the variable argument listva. Unix man pagevsnprintf(3).

PyOS_snprintf() andPyOS_vsnprintf() wrap the Standard C libraryfunctionssnprintf() andvsnprintf(). Their purpose is toguarantee consistent behavior in corner cases, which the Standard C functions donot.

The wrappers ensure thatstr[size-1] is always'\0' upon return. Theynever write more thansize bytes (including the trailing'\0') into str.Both functions require thatstr!=NULL,size>0 andformat!=NULL.

If the platform doesn’t havevsnprintf() and the buffer size needed toavoid truncation exceedssize by more than 512 bytes, Python aborts with aPy_FatalError().

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

  • When0<=rv<size, the output conversion was successful andrvcharacters were written tostr (excluding the trailing'\0' byte atstr[rv]).

  • Whenrv>=size, the output conversion was truncated and a buffer withrv+1 bytes would have been needed to succeed.str[size-1] is'\0'in this case.

  • Whenrv<0, “something bad happened.”str[size-1] is'\0' inthis case too, but the rest ofstr is undefined. The exact cause of the errordepends on the underlying platform.

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

doublePyOS_string_to_double(const char *s, char **endptr,PyObject *overflow_exception)

Convert a strings to adouble, raising a Pythonexception on failure. The set of accepted strings corresponds tothe set of strings accepted by Python’sfloat() constructor,except thats must not have leading or trailing whitespace.The conversion is independent of the current locale.

Ifendptr isNULL, convert the whole string. RaiseValueError and return-1.0 if the string is not a validrepresentation of a floating-point number.

If endptr is notNULL, convert as much of the string aspossible and set*endptr to point to the first unconvertedcharacter. If no initial segment of the string is the validrepresentation of a floating-point number, set*endptr to pointto the beginning of the string, raise ValueError, and return-1.0.

Ifs represents a value that is too large to store in a float(for example,"1e500" is such a string on many platforms) thenifoverflow_exception isNULL returnPy_HUGE_VAL (withan 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 anout-of-memory error), set the appropriate Python exception andreturn-1.0.

New in version 3.1.

char*PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

Convert adoubleval to a string using suppliedformat_code,precision, andflags.

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

flags can be zero or more of the valuesPy_DTSF_SIGN,Py_DTSF_ADD_DOT_0, orPy_DTSF_ALT, or-ed together:

  • Py_DTSF_SIGN means to always precede the returned string with a signcharacter, even ifval is non-negative.

  • Py_DTSF_ADD_DOT_0 means to ensure that the returned string will not looklike an integer.

  • Py_DTSF_ALT means to apply “alternate” formatting rules. See thedocumentation for thePyOS_snprintf()'#' specifier fordetails.

Ifptype is non-NULL, then the value it points to will be set to one ofPy_DTST_FINITE,Py_DTST_INFINITE, orPy_DTST_NAN, signifying thatval is a finite number, an infinite number, or not a number, respectively.

The return value is a pointer tobuffer with the converted string orNULL if the conversion failed. The caller is responsible for freeing thereturned string by callingPyMem_Free().

New in version 3.1.

intPyOS_stricmp(const char *s1, const char *s2)

Case insensitive comparison of strings. The function works almostidentically tostrcmp() except that it ignores the case.

intPyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

Case insensitive comparison of strings. The function works almostidentically tostrncmp() except that it ignores the case.