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

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

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'. Они никогда не записывают в str больше size байт (включая завершающий байт '\0'). Для обеих функций требуется, чтобы 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 в случае ошибки. Набор допустимых строк соответствует набору строк, принимаемых конструктором float() в Python, за исключением того, что 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(), но игнорирует регистр.