Перетворення та форматування рядків

Функції для перетворення чисел і виведення форматованого рядка.

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Part of the Stable ABI.

Виводити не більше size байтів до str відповідно до рядка формату format і додаткових аргументів. Перегляньте сторінку довідки Unix snprintf(3).

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

Part of the Stable ABI.

Виводити не більше size байтів до str відповідно до рядка формату format і списку змінних аргументів va. Довідкова сторінка Unix vsnprintf(3).

PyOS_snprintf() і PyOS_vsnprintf() обгортають стандартні функції бібліотеки C snprintf() і vsnprintf(). Їх мета полягає в тому, щоб гарантувати послідовну поведінку в кутових випадках, чого немає у стандартних функціях C.

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.

Повернене значення (rv) для цих функцій слід інтерпретувати таким чином:

• Коли 0 <= rv < size, вихідне перетворення було успішним і rv символи були записані в str (за винятком кінцевого байта '\0'' у str[rv] ).

• Коли rv >= size, вихідне перетворення було скорочено, і для успіху знадобився буфер із rv + 1 байтами. str[size-1] у цьому випадку є '\0''.

• 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.

Наступні функції забезпечують перетворення рядка в число, незалежне від локалі.

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)

Part of the Stable 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 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 strtoul(3).

Added in version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)

Part of the Stable ABI.

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 PyOS_strtoul(), but return a long value instead and LONG_MAX on overflows.

See also the Unix man page strtol(3).

Added in version 3.2.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

Part of the Stable ABI.

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 float() constructor, except that s must not have leading or trailing whitespace. The conversion is independent of the current locale.

Якщо endptr має значення NULL, перетворити весь рядок. Викликайте ValueError і повертайте -1.0, якщо рядок не є дійсним представленням числа з плаваючою комою.

Якщо endptr не дорівнює NULL, перетворіть якомога більшу частину рядка та встановіть *endptr так, щоб він вказував на перший неперетворений символ. Якщо жоден початковий сегмент рядка не є дійсним представленням числа з плаваючою комою, установіть *endptr, щоб вказувати на початок рядка, викликайте ValueError і поверніть -1.0.

Якщо s представляє значення, яке є надто великим для зберігання в float (наприклад, "1e500" є таким рядком на багатьох платформах), тоді overflow_exception має значення NULL поверніть Py_HUGE_VAL (з відповідним знаком) і не встановлюйте винятків. В іншому випадку overflow_exception має вказувати на об’єкт винятку Python; викликати цей виняток і повернути -1.0. В обох випадках встановіть *endptr, щоб вказувати на перший символ після перетвореного значення.

Якщо під час перетворення виникає будь-яка інша помилка (наприклад, помилка браку пам’яті), установіть відповідний виняток Python і поверніть -1.0.

Added in version 3.1.

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

Part of the Stable ABI.

Convert a double val to a string using supplied format_code, precision, and flags.

format_code має бути одним із 'e', 'E', 'f', 'F', 'g', 'G' або 'r''. Для 'r' надана точність має бути 0 і ігнорується. Код формату 'r' визначає стандартний формат repr().

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 PyOS_snprintf() '#' specifier for details.

Py_DTSF_NO_NEG_0

Negative zero is converted to positive zero.

Added in version 3.11.

Якщо ptype не є NULL, тоді значення, на яке він вказує, буде встановлено на одне з Py_DTST_FINITE, Py_DTST_INFINITE або Py_DTST_NAN, що означає, що val є кінцеве число, нескінченне число або не число відповідно.

Поверненим значенням є вказівник на buffer із перетвореним рядком або NULL, якщо перетворення не вдалося. Виклик відповідає за звільнення повернутого рядка шляхом виклику PyMem_Free().

Added in version 3.1.

int PyOS_mystricmp(const char *str1, const char *str2)

int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)

Part of the Stable ABI.

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.

int PyOS_stricmp(const char *str1, const char *str2)

int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)

Case insensitive comparison of strings.

On Windows, these are aliases of stricmp() and strnicmp(), respectively.

On other platforms, they are aliases of PyOS_mystricmp() and PyOS_mystrnicmp(), 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.