字符串转换和格式化

Functions for number conversion and formatted string output.

int PyOS_snprintf ( char * str , size_t size , const char * format , ... )
属于 稳定 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 )
属于 稳定 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:

  • 当 0 <= rv < size , the output conversion was successful and rv characters were written to str (excluding the trailing '\0' byte at str[rv] ).

  • 当 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' 在此情况下。

  • 当 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 )
属于 稳定 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 为非 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 被设为 ERANGE ) 和 ULONG_MAX is returned. If no conversion can be performed, 0 被返回。

See also the Unix man page strtoul(3) .

Added in version 3.2.