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

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

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

• Коли rv < 0, «сталося щось погане». str[size-1] у цьому випадку також є '\0'', але решта str не визначена. Точна причина помилки залежить від основної платформи.

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

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

Нове в версії 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).

Нове в версії 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.

Нове в версії 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 може мати нуль або більше значень Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0 або Py_DTSF_ALT, або об’єднані разом:

• Py_DTSF_SIGN означає, що перед поверненим рядком завжди ставиться знак, навіть якщо val є невід’ємним.

• Py_DTSF_ADD_DOT_0 означає, що повернутий рядок не буде виглядати як ціле число.

• Py_DTSF_ALT означає застосування «альтернативних» правил форматування. Перегляньте документацію для специфікатора PyOS_snprintf() '#'' для отримання детальної інформації.

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

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

Нове в версії 3.1.

int PyOS_stricmp(const char *s1, const char *s2)

Case insensitive comparison of strings. The function works almost identically to strcmp() except that it ignores the case.

int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)

Case insensitive comparison of strings. The function works almost identically to strncmp() except that it ignores the case.