Преобразование строк и форматирование¶String conversion and formatting

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)¶: Часть Stable ABI.
Выводит не более size байт в str в соответствии со строкой формата format и дополнительными аргументами. См. справочную страницу Unix snprintf(3).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)¶: Часть Stable 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, преобразование выполнено успешно, и rv символов записано в str (за исключением завершающего байта '\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)¶

Часть Stable 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)¶

Часть Stable 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)¶

Часть Stable 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, возвращает 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)¶

Часть Stable 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.12.

Если 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)¶

Часть Stable ABI.

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

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

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

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

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() соответственно.

Классификация и преобразование символов¶Character classification and conversion

Следующие макросы предоставляют не зависящую от локали (в отличие от стандартной библиотеки C ctype.h) классификацию и преобразование символов. Аргументом должно быть значение типа signed или unsigned char.

Py_ISALNUM(c)¶: Возвращает истину, если символ c является буквенно-цифровым.

Py_ISALPHA(c)¶: Возвращает истину, если символ c является буквенным символом (a-z и A-Z).

Py_ISDIGIT(c)¶: Возвращает истину, если символ c является десятичной цифрой (0-9).

Py_ISLOWER(c)¶: Возвращает истину, если символ c является строчной буквой ASCII (a-z).

Py_ISUPPER(c)¶: Возвращает истину, если символ c является заглавной буквой ASCII (A-Z).

Py_ISSPACE(c)¶: Возвращает истину, если символ c является пробельным символом (пробел, табуляция, возврат каретки, перевод строки, вертикальная табуляция или перевод страницы).

Py_ISXDIGIT(c)¶: Возвращает истину, если символ c является шестнадцатеричной цифрой (0-9, a-f и A-F).

Py_TOLOWER(c)¶: Возвращает символ c в нижнем регистре.

Py_TOUPPER(c)¶: Возвращает символ c в верхнем регистре.