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

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

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

Часть Стабильной ABI.

Выводит не более size байт в str в соответствии с форматом строки format и дополнительными аргументами. См. страницу руководства Unix snprintf(3).

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

Часть Стабильной ABI.

Выводит не более 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 и size < INT_MAX. Обратите внимание, что это означает, что нет эквивалента функции C99 n = snprintf(NULL, 0, ...), которая бы определяла необходимый размер буфера.

Значение возврата (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)

Часть Стабильной ABI.

Преобразует строку 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)

Часть Стабильной ABI.

Преобразует число с плавающей точкой 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(), за исключением того, что она игнорирует регистр.