Преобразование и форматирование строк

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

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.

Оборачивающие функции гарантируют, что str[size-1] всегда '\0' после возврата. Они никогда не записывают более size байтов (включая завершающий '\0') в str. Обе функции требуют, чтобы str != NULL, size > 0 и format != NULL.

Если на платформе нет vsnprintf(), и размер буфера, необходимый для предотвращения обрезки, превышает size более чем на 512 байт, Python аварийно завершается с ошибкой Py_FatalError().

Значение возврата (rv) для этих функций должно интерпретироваться следующим образом:

• Если 0 <= rv < size, преобразование вывода прошло успешно, и в str были записаны rv символов (исключая завершающий '\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)

Преобразует строку s в double, возбуждая исключение Python при ошибке. Множество допустимых строк соответствует множеству строк, принятых конструктором Python float(), за исключением того, что s не должна иметь начальных или конечных пробелов. Преобразование независимо от текущей локали.

Если endptr равно NULL, преобразуйте всю строку. Поднимите ValueError и верните -1.0 , если строка не является допустимым представлением число с плавающей точкой.

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

Если s представляет значение, которое слишком велико для хранения в плавающей точке (например, "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)

Преобразует double val в строку с использованием предоставленного format_code, precision и flags.

format_code должен быть одним из 'e', 'E', 'f', 'F', 'g', 'G' или 'r'. Для 'r', предоставленное precision должно быть 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)

Сравнение строк без учёта регистра. Функция работает практически так же, как strcmp() , за исключением того, что она игнорирует регистр.

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

Сравнение строк без учёта регистра. Функция работает практически так же, как strncmp() , за исключением того, что она игнорирует регистр.