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

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

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_INFINITY (с соответствующим знаком), и исключение не возбуждается. В противном случае 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

Всегда добавлять знак перед возвращаемой строкой, даже если val неотрицательно.

Py_DTSF_ADD_DOT_0

Гарантировать, что возвращаемая строка не будет выглядеть как целое число.

Py_DTSF_ALT

Применять правила «альтернативного» форматирования. Подробнее см. документацию по спецификатору '#' функции PyOS_snprintf().

Py_DTSF_NO_NEG_0

Отрицательный ноль преобразуется в положительный ноль.

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

Если ptype не равно NULL, то значение, на которое оно указывает, будет установлено в одну из следующих констант в зависимости от типа val:

*ptype	тип val
Py_DTST_FINITE	конечное число
Py_DTST_INFINITE	бесконечное число
Py_DTST_NAN	не число

Возвращаемое значение — указатель на buffer с преобразованной строкой или NULL в случае ошибки преобразования. Вызывающий код должен освободить возвращённую строку, вызвав PyMem_Free().

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

int PyOS_mystricmp(const char *str1, const char *str2)

int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)

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

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

Возвращает 0, если строки равны, отрицательное значение, если str1 лексикографически предшествует str2, или положительное значение, если следует за ним.

В аргументах str1 или str2 байт NUL обозначает конец строки. Для PyOS_mystrnicmp() аргумент size задаёт максимальный размер строки, как если бы по индексу size находился символ NUL.

Эти функции не используют локаль.

int PyOS_stricmp(const char *str1, const char *str2)

int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)

Сравнение строк без учёта регистра.

В Windows это псевдонимы stricmp() и strnicmp() соответственно.

На других платформах это псевдонимы PyOS_mystricmp() и PyOS_mystrnicmp() соответственно.