`conversion.md`

180 строк · 15.1 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.15/c-api/conversion.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Преобразование строк и форматирование89Функции для преобразования чисел и форматированного вывода строк.1011#### `int PyOS_snprintf(char *str, size_t size, const char *format, ...)`1213*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*1415Выводит не более *size* байт в *str* в соответствии со строкой формата *format* и дополнительными аргументами. См. справочную страницу Unix *[snprintf(3)](https://python-all.ru/3.15/c-api/conversion.html)*.1617#### `int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)`1819*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*2021Выводит не более *size* байт в *str* в соответствии со строкой формата *format* и со списком переменных аргументов *va*. Справочная страница Unix *[vsnprintf(3)](https://python-all.ru/3.15/c-api/conversion.html)*.2223[`PyOS_snprintf()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_snprintf) и [`PyOS_vsnprintf()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_vsnprintf) оборачивают функции стандартной библиотеки C `snprintf()` и `vsnprintf()`. Их задача – гарантировать согласованное поведение в граничных случаях, чего не обеспечивают стандартные функции C.2425Обёртки гарантируют, что `str[size-1]` всегда будет `'\0'` после возврата. Они никогда не записывают в str более *size* байт (включая завершающий `'\0'`). Обе функции требуют, чтобы `str != NULL`, `size > 0`, `format != NULL` и `size < INT_MAX`. Обратите внимание, что это означает отсутствие эквивалента функции C99 `n = snprintf(NULL, 0, ...)`, которая определяла бы необходимый размер буфера.2627Возвращаемое значение (*rv*) для этих функций следует интерпретировать следующим образом:2829- Если `0 <= rv < size`, преобразование выполнено успешно, и *rv* символов записано в *str* (за исключением завершающего байта `'\0'` по адресу `str[rv]`).30- Если `rv >= size`, преобразование было усечено, и для успешного выполнения потребовался бы буфер размером `rv + 1` байт. В этом случае `str[size-1]` равно `'\0'`.31- Если `rv < 0`, преобразование не удалось, и `str[size-1]` также равно `'\0'` в этом случае, но остальная часть *str* не определена. Точная причина ошибки зависит от базовой платформы.3233Следующие функции предоставляют преобразование строк в числа, не зависящее от локали.3435#### `unsigned long PyOS_strtoul(const char *str, char **ptr, int base)`3637*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*3839Преобразует начальную часть строки из `str` в значение unsigned long в соответствии с заданным `base`, которое должно быть между `2` и `36` включительно, или быть специальным значением `0`.4041Начальные пробелы и регистр символов игнорируются. Если `base` равно нулю, функция ищет начальные `0b`, `0o` или `0x`, чтобы определить основание. Если они отсутствуют, по умолчанию используется `10`. Основание должно быть 0 или от 2 до 36 (включительно). Если `ptr` не равно `NULL`, оно будет содержать указатель на конец разбора.4243Если преобразованное значение выходит за пределы соответствующего типа возврата, возникает ошибка диапазона (`errno` устанавливается в `ERANGE`) и возвращается `ULONG_MAX`. Если преобразование невозможно, возвращается `0`.4445См. также справочную страницу Unix *[strtoul(3)](https://python-all.ru/3.15/c-api/conversion.html)*.4647Добавлено в версии 3.2.4849#### `long PyOS_strtol(const char *str, char **ptr, int base)`5051*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*5253Преобразует начальную часть строки из `str` в значение long в соответствии с заданным `base`, которое должно быть между `2` и `36` включительно, или быть специальным значением `0`.5455То же, что [`PyOS_strtoul()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_strtoul), но возвращает значение long и `LONG_MAX` при переполнении.5657См. также справочную страницу Unix *[strtol(3)](https://python-all.ru/3.15/c-api/conversion.html)*.5859Добавлено в версии 3.2.6061#### `double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)`6263*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*6465Преобразует строку `s` в значение double, возбуждая исключение Python при неудаче. Множество допустимых строк соответствует строкам, принимаемым конструктором [`float()`](https://python-all.ru/3.15/library/functions.html#float) в Python, за исключением того, что `s` не должно содержать начальных или конечных пробелов. Преобразование не зависит от текущей локали.6667Если `endptr` равно `NULL`, преобразует всю строку. Возбуждает [`ValueError`](https://python-all.ru/3.15/library/exceptions.html#ValueError) и возвращает `-1.0`, если строка не является допустимым представлением числа с плавающей запятой.6869Если endptr не равно `NULL`, преобразует максимально возможную часть строки и устанавливает `*endptr` так, чтобы он указывал на первый непреобразованный символ. Если ни один начальный сегмент строки не является допустимым представлением числа с плавающей запятой, устанавливает `*endptr` так, чтобы он указывал на начало строки, возбуждает ValueError и возвращает `-1.0`.7071Если `s` представляет значение, слишком большое для хранения в float (например, `"1e500"` является такой строкой на многих платформах), то если `overflow_exception` равно `NULL`, возвращает `INFINITY` (с соответствующим знаком) и не устанавливает никакого исключения. В противном случае, `overflow_exception` должен указывать на объект исключения Python; возбуждает это исключение и возвращает `-1.0`. В обоих случаях устанавливает `*endptr` так, чтобы он указывал на первый символ после преобразованного значения.7273Если во время преобразования возникает любая другая ошибка (например, ошибка нехватки памяти), устанавливает соответствующее исключение Python и возвращает `-1.0`.7475Добавлено в версии 3.1.7677#### `char *PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)`7879*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*8081Преобразует double *val* в строку, используя переданные *format\_code*, *precision* и *flags*.8283*format\_code* должен быть одним из `'e'`, `'E'`, `'f'`, `'F'`, `'g'`, `'G'` или `'r'`. Для `'r'` переданная *precision* должна быть равна 0 и игнорируется. Код формата `'r'` задаёт стандартный формат [`repr()`](https://python-all.ru/3.15/library/functions.html#repr).8485*flags* может содержать ноль или более следующих значений, объединённых логическим ИЛИ:8687#### `Py_DTSF_SIGN`8889Всегда предваряет возвращаемую строку знаком, даже если *val* неотрицательно.9091#### `Py_DTSF_ADD_DOT_0`9293Гарантирует, что возвращаемая строка не будет выглядеть как целое число.9495#### `Py_DTSF_ALT`9697Применить альтернативные правила форматирования. Подробнее см. документацию по спецификатору [`PyOS_snprintf()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_snprintf) `'#'`.9899#### `Py_DTSF_NO_NEG_0`100101Отрицательный ноль преобразуется в положительный ноль.102103Добавлено в версии 3.12.104105Если *ptype* не равен `NULL`, то значение, на которое он указывает, будет установлено в одну из следующих констант в зависимости от типа *val*:106107| *\*ptype* | тип *val* |108| --- | --- |109| Py\_DTST\_FINITE | конечное число |110| Py\_DTST\_INFINITE | бесконечное число |111| Py\_DTST\_NAN | не число |112113Возвращаемое значение – указатель на *buffer* с преобразованной строкой или `NULL`, если преобразование не удалось. Вызывающий отвечает за освобождение возвращённой строки с помощью вызова [`PyMem_Free()`](https://python-all.ru/3.15/c-api/memory.html#c.PyMem_Free).114115Добавлено в версии 3.1.116117#### `int PyOS_mystricmp(const char *str1, const char *str2)`118119#### `int PyOS_mystrnicmp(const char *str1, const char *str2, Py_ssize_t size)`120121*Часть [Stable ABI](https://python-all.ru/3.15/c-api/stable.html#stable).*122123Регистронезависимое сравнение строк. Эти функции работают почти так же, как `strcmp()` и `strncmp()` (соответственно), за исключением того, что они игнорируют регистр символов ASCII.124125Возвращает `0`, если строки равны, отрицательное значение, если *str1* лексикографически меньше *str2*, или положительное, если больше.126127В аргументах *str1* или *str2* нулевой байт (NUL) обозначает конец строки. Для `PyOS_mystrnicmp()` аргумент *size* задаёт максимальный размер строки, как если бы NUL находился по индексу, указанному *size*.128129Эти функции не используют локаль.130131#### `int PyOS_stricmp(const char *str1, const char *str2)`132133#### `int PyOS_strnicmp(const char *str1, const char *str2, Py_ssize_t size)`134135Регистронезависимое сравнение строк.136137В Windows это псевдонимы `stricmp()` и `strnicmp()` соответственно.138139На других платформах они являются псевдонимами [`PyOS_mystricmp()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_mystricmp) и [`PyOS_mystrnicmp()`](https://python-all.ru/3.15/c-api/conversion.html#c.PyOS_mystrnicmp) соответственно.140141# Классификация и преобразование символов142143Следующие макросы предоставляют не зависящую от локали (в отличие от стандартной библиотеки C `ctype.h`) классификацию и преобразование символов. Аргументом должно быть значение типа signed или unsigned char.144145#### `Py_ISALNUM(c)`146147Возвращает истину, если символ *c* является буквенно-цифровым.148149#### `Py_ISALPHA(c)`150151Возвращает истину, если символ *c* является буквенным символом (`a-z` и `A-Z`).152153#### `Py_ISDIGIT(c)`154155Возвращает истину, если символ *c* является десятичной цифрой (`0-9`).156157#### `Py_ISLOWER(c)`158159Возвращает истину, если символ *c* является строчной буквой ASCII (`a-z`).160161#### `Py_ISUPPER(c)`162163Возвращает истину, если символ *c* является заглавной буквой ASCII (`A-Z`).164165#### `Py_ISSPACE(c)`166167Возвращает истину, если символ *c* является пробельным символом (пробел, табуляция, возврат каретки, перевод строки, вертикальная табуляция или перевод страницы).168169#### `Py_ISXDIGIT(c)`170171Возвращает истину, если символ *c* является шестнадцатеричной цифрой (`0-9`, `a-f` и `A-F`).172173#### `Py_TOLOWER(c)`174175Возвращает символ *c* в нижнем регистре.176177#### `Py_TOUPPER(c)`178179Возвращает символ *c* в верхнем регистре.180