String conversion and formatting

Functions for number conversion and formatted string output.

intPyOS_snprintf(char*str,size_tsize,constchar*format,...)
Part of theStable ABI.

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_tsize,constchar*format,va_listva)
Part of theStable ABI.

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

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.

unsignedlongPyOS_strtoul(constchar*str,char**ptr,intbase)
Part of theStable ABI.

Convert the initial part of the string instr to anunsignedlong value according to the givenbase, which must be between2 and36 inclusive, or be the special value0.

Leading white space and case of characters are ignored. Ifbase is zeroit looks for a leading0b,0o or0x to tell which base. Ifthese are absent it defaults to10. Base must be 0 or between 2 and 36(inclusive). Ifptr is non-NULL it will contain a pointer to theend of the scan.

If the converted value falls out of range of corresponding return type,range error occurs (errno is set toERANGE) andULONG_MAX is returned. If no conversion can be performed,0is returned.

See also the Unix man pagestrtoul(3).

Added in version 3.2.

longPyOS_strtol(constchar*str,char**ptr,intbase)
Part of theStable ABI.

Convert the initial part of the string instr to anlong valueaccording to the givenbase, which must be between2 and36inclusive, or be the special value0.

Same asPyOS_strtoul(), but return along value insteadandLONG_MAX on overflows.

See also the Unix man pagestrtol(3).

Added in version 3.2.

doublePyOS_string_to_double(constchar*s,char**endptr,PyObject*overflow_exception)
Part of theStable ABI.

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.

Added in version 3.1.

char*PyOS_double_to_string(doubleval,charformat_code,intprecision,intflags,int*ptype)
Part of theStable ABI.

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().

Added in version 3.1.

intPyOS_stricmp(constchar*s1,constchar*s2)

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

intPyOS_strnicmp(constchar*s1,constchar*s2,Py_ssize_tsize)

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