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, the output conversion failed andstr[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_INFINITY (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 following values or-ed together:

Py_DTSF_SIGN

Always precede the returned string with a signcharacter, even ifval is non-negative.

Py_DTSF_ADD_DOT_0

Ensure that the returned string will not look like an integer.

Py_DTSF_ALT

Apply “alternate” formatting rules.See the documentation for thePyOS_snprintf()'#' specifier fordetails.

Py_DTSF_NO_NEG_0

Negative zero is converted to positive zero.

Added in version 3.11.

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_mystricmp(constchar*str1,constchar*str2)
intPyOS_mystrnicmp(constchar*str1,constchar*str2,Py_ssize_tsize)
Part of theStable ABI.

Case insensitive comparison of strings. These functions work almostidentically tostrcmp() andstrncmp() (respectively),except that they ignore the case of ASCII characters.

Return0 if the strings are equal, a negative value ifstr1 sortslexicographically beforestr2, or a positive value if it sorts after.

In thestr1 orstr2 arguments, a NUL byte marks the end of the string.ForPyOS_mystrnicmp(), thesize argument gives the maximum sizeof the string, as if NUL was present at the index given bysize.

These functions do not use the locale.

intPyOS_stricmp(constchar*str1,constchar*str2)
intPyOS_strnicmp(constchar*str1,constchar*str2,Py_ssize_tsize)

Case insensitive comparison of strings.

On Windows, these are aliases ofstricmp() andstrnicmp(),respectively.

On other platforms, they are aliases ofPyOS_mystricmp() andPyOS_mystrnicmp(), respectively.

Character classification and conversion

The following macros provide locale-independent (unlike the C standard libraryctype.h) character classification and conversion.The argument must be a signed or unsignedchar.

Py_ISALNUM(c)

Return true if the characterc is an alphanumeric character.

Py_ISALPHA(c)

Return true if the characterc is an alphabetic character (a-z andA-Z).

Py_ISDIGIT(c)

Return true if the characterc is a decimal digit (0-9).

Py_ISLOWER(c)

Return true if the characterc is a lowercase ASCII letter (a-z).

Py_ISUPPER(c)

Return true if the characterc is an uppercase ASCII letter (A-Z).

Py_ISSPACE(c)

Return true if the characterc is a whitespace character (space, tab,carriage return, newline, vertical tab, or form feed).

Py_ISXDIGIT(c)

Return true if the characterc is a hexadecimal digit (0-9,a-f, andA-F).

Py_TOLOWER(c)

Return the lowercase equivalent of the characterc.

Py_TOUPPER(c)

Return the uppercase equivalent of the characterc.