`conversion.md`

72 строк · 9.3 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.8/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Выводит не более *size* байт в *str* в соответствии со строкой формата *format* и дополнительными аргументами. См. справочную страницу Unix *[snprintf(3)](https://python-all.ru/3.8/c-api/conversion.html)*.1415#### `int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)`1617Выводит не более *size* байт в *str* в соответствии со строкой формата *format* и со списком переменных аргументов *va*. Справочная страница Unix *[vsnprintf(3)](https://python-all.ru/3.8/c-api/conversion.html)*.1819[`PyOS_snprintf()`](https://python-all.ru/3.8/c-api/conversion.html#c.PyOS_snprintf) и [`PyOS_vsnprintf()`](https://python-all.ru/3.8/c-api/conversion.html#c.PyOS_vsnprintf) оборачивают функции стандартной библиотеки C `snprintf()` и `vsnprintf()`. Их задача – гарантировать согласованное поведение в граничных случаях, чего не обеспечивают стандартные функции C.2021Обёртки гарантируют, что `str[size-1]` всегда `'\0'` при возврате. Они никогда не записывают более *size* байт (включая завершающий `'\0'`) в str. Обе функции требуют, что `str != NULL`, `size > 0` и `format != NULL`.2223Если платформа не имеет `vsnprintf()` и размер буфера, необходимый для предотвращения усечения, превышает *size* более чем на 512 байт, Python аварийно завершается с [`Py_FatalError()`](https://python-all.ru/3.8/c-api/sys.html#c.Py_FatalError).2425Возвращаемое значение (*rv*) для этих функций следует интерпретировать следующим образом:2627- Если `0 <= rv < size`, преобразование выполнено успешно, и *rv* символов записано в *str* (за исключением завершающего байта `'\0'` по адресу `str[rv]`).28- Если `rv >= size`, преобразование было усечено, и для успешного выполнения потребовался бы буфер размером `rv + 1` байт. В этом случае `str[size-1]` равно `'\0'`.29- Если `rv < 0`, «произошла ошибка». `str[size-1]` в этом случае тоже `'\0'`, но остальная часть *str* не определена. Точная причина ошибки зависит от базовой платформы.3031Следующие функции предоставляют преобразование строк в числа, не зависящее от локали.3233#### `double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)`3435Преобразует строку `s` в `double`, возбуждая исключение Python при ошибке. Множество принимаемых строк соответствует множеству строк, принимаемых конструктором [`float()`](https://python-all.ru/3.8/library/functions.html#float) Python, за исключением того, что `s` не должен содержать начальных или конечных пробелов. Преобразование не зависит от текущей локали.3637Если `endptr` равно `NULL`, преобразует всю строку. Возбуждает [`ValueError`](https://python-all.ru/3.8/library/exceptions.html#ValueError) и возвращает `-1.0`, если строка не является допустимым представлением числа с плавающей запятой.3839Если endptr не равно `NULL`, преобразует максимально возможную часть строки и устанавливает `*endptr` так, чтобы он указывал на первый непреобразованный символ. Если ни один начальный сегмент строки не является допустимым представлением числа с плавающей запятой, устанавливает `*endptr` так, чтобы он указывал на начало строки, возбуждает ValueError и возвращает `-1.0`.4041Если `s` представляет значение, слишком большое для хранения в float (например, `"1e500"` является такой строкой на многих платформах), то если `overflow_exception` равно `NULL`, возвращает `Py_HUGE_VAL` (с соответствующим знаком) и не устанавливает никакого исключения. В противном случае, `overflow_exception` должен указывать на объект исключения Python; возбуждает это исключение и возвращает `-1.0`. В обоих случаях устанавливает `*endptr` так, чтобы он указывал на первый символ после преобразованного значения.4243Если во время преобразования возникает любая другая ошибка (например, ошибка нехватки памяти), устанавливает соответствующее исключение Python и возвращает `-1.0`.4445Новое в версии 3.1.4647#### `char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)`4849Преобразует `double` *val* в строку, используя заданные *format\_code*, *precision* и *flags*.5051*format\_code* должен быть одним из `'e'`, `'E'`, `'f'`, `'F'`, `'g'`, `'G'` или `'r'`. Для `'r'` переданная *precision* должна быть равна 0 и игнорируется. Код формата `'r'` задаёт стандартный формат [`repr()`](https://python-all.ru/3.8/library/functions.html#repr).5253*flags* может быть нулём или комбинацией значений `Py_DTSF_SIGN`, `Py_DTSF_ADD_DOT_0` или `Py_DTSF_ALT`, объединённых логическим ИЛИ.5455- `Py_DTSF_SIGN` означает, что возвращаемая строка всегда будет начинаться с символа знака, даже если *val* неотрицательно.56- `Py_DTSF_ADD_DOT_0` гарантирует, что возвращаемая строка не будет похожа на целое число.57- `Py_DTSF_ALT` означает применение «альтернативных» правил форматирования. См. описание спецификатора [`PyOS_snprintf()`](https://python-all.ru/3.8/c-api/conversion.html#c.PyOS_snprintf) `'#'` для подробностей.5859Если *ptype* не равно `NULL`, то значение, на которое он указывает, будет установлено в одно из `Py_DTST_FINITE`, `Py_DTST_INFINITE` или `Py_DTST_NAN`, что означает, что *val* является конечным числом, бесконечностью или не числом соответственно.6061Возвращаемое значение – указатель на *buffer* с преобразованной строкой или `NULL`, если преобразование не удалось. Вызывающий отвечает за освобождение возвращённой строки с помощью вызова [`PyMem_Free()`](https://python-all.ru/3.8/c-api/memory.html#c.PyMem_Free).6263Новое в версии 3.1.6465#### `int PyOS_stricmp(const char *s1, const char *s2)`6667Сравнение строк без учёта регистра. Функция работает почти идентично `strcmp()`, за исключением того, что игнорирует регистр.6869#### `int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t size)`7071Сравнение строк без учёта регистра. Функция работает почти идентично `strncmp()`, за исключением того, что игнорирует регистр.72