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

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

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, объединенных побитовой операцией OR:

• 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(), но игнорирует регистр.