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

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

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 не определена. Точная причина ошибки зависит от платформы.

Следующие функции обеспечивают независимое от локали преобразование строк в числа.

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

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

Преобразует начальную часть строки в str в значение типа unsigned long в соответствии с заданным base, который должен быть между 2 и 36 включительно, или специальным значением 0.

Пробелы в начале и регистр символов игнорируются. Если base равно нулю, ищется ведущий 0b, 0o или 0x для определения основания. Если они отсутствуют, используется 10. Основание должно быть 0 или от 2 до 36 включительно. Если ptr не NULL, он будет содержать указатель на конец сканирования.

Если преобразованное значение выходит за пределы диапазона соответствующего типа возврата, происходит ошибка диапазона (errno устанавливается в ERANGE) и возвращается ULONG_MAX. Если преобразование не может быть выполнено, возвращается 0.

См. также страницу руководства Unix strtoul(3).

Добавлена в версии 3.2.

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

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

Преобразует начальную часть строки в str в значение типа long в соответствии с заданным base, который должен быть между 2 и 36 включительно, или специальным значением 0.

Аналогично PyOS_strtoul(), но возвращает значение типа long и LONG_MAX при переполнении.

См. также страницу руководства Unix strtol(3).

Добавлена в версии 3.2.

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 представляет значение, слишком большое для хранения в 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)

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

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