Документация Python неофициальный перевод

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

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

int PyOS_snprintf(char *str, size_t size, const char *format, ...)

Вывод не более size байт в str в соответствии со строкой форматирования format и дополнительными аргументами. См. справочную страницу Unix snprintf(2).

int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)

Вывод не более size байт в str в соответствии со строкой форматирования format и списком переменных аргументов va. Справочная страница Unix vsnprintf(2).

PyOS_snprintf() и PyOS_vsnprintf() оборачивают функции стандартной библиотеки C snprintf() и vsnprintf(). Их задача – гарантировать согласованное поведение в граничных случаях, чего не обеспечивают стандартные функции C.

Обёртки гарантируют, что str*[*size-1] всегда содержит '\0' при возврате. Они никогда не записывают более size байт (включая завершающий '\0') в str. Обе функции требуют, чтобы str != NULL, size > 0 и format != NULL.

Если платформа не поддерживает vsnprintf() и размер буфера, необходимый для предотвращения усечения, превышает size более чем на 512 байт, Python аварийно завершает работу с Py_FatalError.

Возвращаемое значение (rv) для этих функций следует интерпретировать следующим образом:

  • Если 0 <= rv < size, преобразование вывода прошло успешно, и rv символов было записано в str (исключая завершающий байт '\0' по адресу str*[*rv]).

  • Если rv >= size, преобразование вывода было усечено, и для успеха потребовался бы буфер размером rv + 1 байт. В этом случае str*[*size-1] равен '\0'.

  • Если rv < 0, «произошло что-то плохое». В этом случае str*[*size-1] также равен '\0', но остальная часть str не определена. Точная причина ошибки зависит от базовой платформы.

Следующие функции предоставляют преобразование строк в числа, не зависящее от локали.

double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)

Преобразует строку 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.

Новое в версии 2.7.

double PyOS_ascii_strtod(const char *nptr, char **endptr)

Преобразует строку в double. Эта функция ведёт себя как стандартная C-функция strtod() в локали C. Она делает это без изменения текущей локали, так как это не было бы потокобезопасным.

PyOS_ascii_strtod() обычно следует использовать для чтения конфигурационных файлов или других данных, вводимых не пользователем, которые должны быть независимыми от локали.

Подробнее см. на странице руководства Unix strtod(2).

Новое в версии 2.4.

Устарело с версии 2.7: Используйте вместо этого PyOS_string_to_double().

char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)

Преобразует double в строку, используя '.' в качестве десятичного разделителя. format – это строка формата в стиле printf(), задающая формат числа. Допустимые символы преобразования: 'e', 'E', 'f', 'F', 'g' и 'G'.

Возвращаемое значение – указатель на buffer с преобразованной строкой или NULL, если преобразование не удалось.

Новое в версии 2.4.

Устарело с версии 2.7: Эта функция удалена в Python 2.7 и 3.1. Используйте вместо этого PyOS_double_to_string().

char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)

Преобразует 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, объединённых по ИЛИ:

  • 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().

Новое в версии 2.7.

double PyOS_ascii_atof(const char *nptr)

Преобразует строку в double независимым от локали способом.

Подробнее см. на странице руководства Unix atof(2).

Новое в версии 2.4.

Устарело с версии 3.1: Используйте вместо этого PyOS_string_to_double().

char* PyOS_stricmp(char *s1, char *s2)

Сравнение строк без учёта регистра. Функция работает почти идентично strcmp(), за исключением того, что игнорирует регистр.

Новое в версии 2.6.

char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)

Сравнение строк без учёта регистра. Функция работает почти идентично strncmp(), за исключением того, что игнорирует регистр.

Новое в версии 2.6.