Functions for number conversion and formatted string output.
intPyOS_snprintf(char*str, size_tsize, constchar*format, ...)
Part of the
.Output not more than size bytes to str according to the format string format and the extra arguments. See the Unix man page
.
intPyOS_vsnprintf(char*str, size_tsize, constchar*format, va_listva)
Part of the
.Output not more than size bytes to str according to the format string format and the variable argument list va. Unix man page
.
and
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, the output conversion failed and 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.
unsignedlongPyOS_strtoul(constchar*str, char**ptr, intbase)
Part of the
.Convert the initial part of the string in str to an unsignedlong 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
.
Added in version 3.2.
longPyOS_strtol(constchar*str, char**ptr, intbase)
Part of the
.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
, but return a long value instead and LONG_MAX on overflows.
See also the Unix man page
.
Added in version 3.2.
doublePyOS_string_to_double(constchar*s, char**endptr,
*overflow_exception)
Part of the
.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
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
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_INFINITY (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.
Added in version 3.1.
char*PyOS_double_to_string(doubleval, charformat_code, intprecision, intflags, int*ptype)
Part of the
.Convert a doubleval 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
format.
flags can be zero or more of the following values or-ed together:
Py_DTSF_SIGN
Always precede the returned string with a sign character, even if val 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 the
'#' specifier for details.
Py_DTSF_NO_NEG_0
Negative zero is converted to positive zero.
Added in version 3.11.
If ptype is non-NULL, then the value it points to will be set to one of the following constants depending on the type of val:
*ptype
type of val
Py_DTST_FINITE
finite number
Py_DTST_INFINITE
infinite number
Py_DTST_NAN
not a number
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
.
Added in version 3.1.
intPyOS_mystricmp(constchar*str1, constchar*str2)
intPyOS_mystrnicmp(constchar*str1, constchar*str2,
size)
Part of the
.Case insensitive comparison of strings. These functions work almost identically to strcmp() and strncmp() (respectively), except that they ignore the case of ASCII characters.
Return 0 if the strings are equal, a negative value if str1 sorts lexicographically before str2, or a positive value if it sorts after.
In the str1 or str2 arguments, a NUL byte marks the end of the string. For PyOS_mystrnicmp(), the size argument gives the maximum size of the string, as if NUL was present at the index given by size.
These functions do not use the locale.
intPyOS_stricmp(constchar*str1, constchar*str2)
intPyOS_strnicmp(constchar*str1, constchar*str2,
size)
Case insensitive comparison of strings.
On Windows, these are aliases of stricmp() and strnicmp(), respectively.
On other platforms, they are aliases of
and
, respectively.
Character classification and conversion
The following macros provide locale-independent (unlike the C standard library ctype.h) character classification and conversion. The argument must be a signed or unsigned char.
Py_ISALNUM(c)
Return true if the character c is an alphanumeric character.
Py_ISALPHA(c)
Return true if the character c is an alphabetic character (a-z and A-Z).
Py_ISDIGIT(c)
Return true if the character c is a decimal digit (0-9).
Py_ISLOWER(c)
Return true if the character c is a lowercase ASCII letter (a-z).
Py_ISUPPER(c)
Return true if the character c is an uppercase ASCII letter (A-Z).
Py_ISSPACE(c)
Return true if the character c is a whitespace character (space, tab, carriage return, newline, vertical tab, or form feed).
Py_ISXDIGIT(c)
Return true if the character c is a hexadecimal digit (0-9, a-f, and A-F).
Py_TOLOWER(c)
Return the lowercase equivalent of the character c.
Py_TOUPPER(c)
Return the uppercase equivalent of the character c.