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

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

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