conversion.md

1> **Источник:** https://python-all.ru/3.1/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Вывод не более1415*size*1617байт в1819*str*2021в соответствии со строкой форматирования2223*format*2425и дополнительными аргументами. См. справочную страницу Unix2627*snprintf(2)*2829.3031**int `PyOS_vsnprintf`(char *\*str*, size\_t *size*, const char *\*format*, va\_list *va*)**3233Вывод не более3435*size*3637байт в3839*str*4041в соответствии со строкой форматирования4243*format*4445и списком переменных аргументов4647*va*4849. Справочная страница Unix5051*vsnprintf(2)*5253.5455[`PyOS_snprintf()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_snprintf) и [`PyOS_vsnprintf()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_vsnprintf) оборачивают функции стандартной библиотеки C `snprintf()` и `vsnprintf()`. Их цель – гарантировать согласованное поведение в граничных случаях, в котором стандартные функции C не гарантируют.5657Обёртки гарантируют, что *str\*\[\*size*-1\] всегда равен `'\0'` после возврата. Они никогда не записывают более *size* байт (включая завершающий `'\0'`) в str. Обе функции требуют, чтобы `str != NULL`, `size > 0` и `format != NULL`.5859Если на платформе нет `vsnprintf()` и размер буфера, необходимый для предотвращения усечения, превышает *size* более чем на 512 байт, Python аварийно завершается с *Py\_FatalError*.6061Возвращаемое значение (*rv*) для этих функций следует интерпретировать следующим образом:6263- Когда `0 <= rv < size`, преобразование вывода прошло успешно и в *str* было записано *rv* символов (исключая завершающий байт `'\0'` в *str\*\[\*rv*\]).64- Когда `rv >= size`, преобразование вывода было усечено и потребовался бы буфер размером `rv + 1` байт для успешного выполнения. *str\*\[\*size*-1\] равен `'\0'` в этом случае.65- Когда `rv < 0`, «произошло что-то плохое». *str\*\[\*size*-1\] равен `'\0'` и в этом случае, но остальная часть *str* не определена. Точная причина ошибки зависит от базовой платформы.6667Следующие функции предоставляют преобразование строк в числа, не зависящее от локали.6869**double `PyOS_ascii_strtod`(const char *\*nptr*, char *\*\*endptr*)**7071Преобразует строку в `double`. Эта функция ведёт себя как стандартная функция языка C `strtod()` в локали C. Она делает это без переключения текущей локали, так как это не было бы потокобезопасно.7273[`PyOS_ascii_strtod()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_ascii_strtod) обычно следует использовать для чтения конфигурационных файлов или других входных данных, не вводимых пользователем, которые должны быть независимы от локали.7475Подробнее см. на странице руководства Unix *strtod(2)*.7677Устарело с версии 3.1: Вместо этого используйте [`PyOS_string_to_double()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_string_to_double).7879**double `PyOS_string_to_double`(const char *\*s*, char *\*\*endptr*, [PyObject](https://python-all.ru/3.1/c-api/structures.html#PyObject) *\*overflow\_exception*)**8081Преобразует строку `s` в `double`, возбуждая исключение Python при неудаче. Набор принимаемых строк соответствует набору строк, принимаемых конструктором [`float()`](https://python-all.ru/3.1/library/functions.html#float) в Python, за исключением того, что `s` не должна содержать начальных или конечных пробелов. Преобразование не зависит от текущей локали.8283Если `endptr` равен `NULL`, преобразует всю строку. Возбуждает ValueError и возвращает `-1.0`, если строка не является корректным представлением числа с плавающей запятой.8485Если endptr не равен `NULL`, преобразует максимально возможную часть строки и устанавливает `*endptr` так, чтобы он указывал на первый непреобразованный символ. Если ни один начальный сегмент строки не является корректным представлением числа с плавающей запятой, устанавливает `*endptr` так, чтобы он указывал на начало строки, возбуждает ValueError и возвращает `-1.0`.8687Если `s` представляет значение, слишком большое для хранения в float (например, `"1e500"` является такой строкой на многих платформах), то если `overflow_exception` равен `NULL`, возвращает `Py_HUGE_VAL` (с соответствующим знаком) и не устанавливает никакого исключения. В противном случае `overflow_exception` должен указывать на объект исключения Python; возбуждает это исключение и возвращает `-1.0`. В обоих случаях устанавливает `*endptr` так, чтобы он указывал на первый символ после преобразованного значения.8889Если во время преобразования возникает любая другая ошибка (например, ошибка нехватки памяти), устанавливает соответствующее исключение Python и возвращает `-1.0`.9091Новое в версии 3.1.9293**char\* `PyOS_ascii_formatd`(char *\*buffer*, size\_t *buf\_len*, const char *\*format*, double *d*)**9495Преобразует `double` в строку, используя `'.'` в качестве десятичного разделителя. Параметр *format* – это строка формата в стиле `printf()`, задающая формат числа. Допустимые символы преобразования: `'e'`, `'E'`, `'f'`, `'F'`, `'g'` и `'G'`.9697Возвращаемое значение – указатель на *buffer* с преобразованной строкой или NULL, если преобразование не удалось.9899Устарело с версии 3.1: Вместо этого используйте [`PyOS_double_to_string()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_double_to_string).100101**char\* `PyOS_double_to_string`(double *val*, char *format\_code*, int *precision*, int *flags*, int *\*ptype*)**102103Преобразует `double` *val* в строку, используя переданные *format\_code*, *precision* и *flags*.104105*format\_code* должен быть одним из `'e'`, `'E'`, `'f'`, `'F'`, `'g'`, `'G'` или `'r'`. Для `'r'` указанный *precision* должен быть 0 и игнорируется. Код формата `'r'` задаёт стандартный формат [`repr()`](https://python-all.ru/3.1/library/functions.html#repr).106107*flags* может быть нулевым или содержать одно или несколько значений *Py\_DTSF\_SIGN*, *Py\_DTSF\_ADD\_DOT\_0* или *Py\_DTSF\_ALT*, объединённых по ИЛИ:108109- *Py\_DTSF\_SIGN* означает, что возвращаемая строка всегда предваряется знаком, даже если *val* неотрицательно.110- *Py\_DTSF\_ADD\_DOT\_0* означает, что возвращаемая строка не должна выглядеть как целое число.111- *Py\_DTSF\_ALT* означает применение «альтернативных» правил форматирования. См. документацию по спецификатору [`PyOS_snprintf()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_snprintf) `'#'` для подробностей.112113Если *ptype* не равен NULL, то значение, на которое он указывает, будет установлено в одно из *Py\_DTST\_FINITE*, *Py\_DTST\_INFINITE* или *Py\_DTST\_NAN*, что означает, что *val* является конечным числом, бесконечностью или не числом соответственно.114115Возвращаемое значение – указатель на *buffer* с преобразованной строкой или *NULL*, если преобразование не удалось. Вызывающий обязан освободить возвращённую строку с помощью вызова [`PyMem_Free()`](https://python-all.ru/3.1/c-api/memory.html#PyMem_Free).116117Новое в версии 3.1.118119**double `PyOS_ascii_atof`(const char *\*nptr*)**120121Преобразует строку в `double` способом, не зависящим от локали.122123Подробнее см. на странице руководства Unix *atof(2)*.124125Устарело с версии 3.1: Вместо этого используйте [`PyOS_string_to_double()`](https://python-all.ru/3.1/c-api/conversion.html#PyOS_string_to_double).126127**char\* `PyOS_stricmp`(char *\*s1*, char *\*s2*)**128129Сравнение строк без учёта регистра. Функция работает почти идентично130131`strcmp()`132133, за исключением того, что игнорирует регистр.134135**char\* `PyOS_strnicmp`(char *\*s1*, char *\*s2*, Py\_ssize\_t *size*)**136137Сравнение строк без учёта регистра. Функция работает почти идентично138139`strncmp()`140141, за исключением того, что игнорирует регистр.142