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

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

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