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

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

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

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

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

Виводити не більше 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 and format != NULL.

If the platform doesn’t have vsnprintf() and the buffer size needed to avoid truncation exceeds size by more than 512 bytes, Python aborts with a Py_FatalError().

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

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

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

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

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

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

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)

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.