Документация 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, преобразование вывода прошло успешно и в str было записано rv символов (исключая завершающий байт '\0' в str*[*rv]).
  • Когда rv >= size, преобразование вывода было усечено и потребовался бы буфер размером rv + 1 байт для успешного выполнения. str*[*size-1] равен '\0' в этом случае.
  • Когда rv < 0, «произошло что-то плохое». str*[*size-1] равен '\0' и в этом случае, но остальная часть str не определена. Точная причина ошибки зависит от базовой платформы.

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

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

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

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

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

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, если преобразование не удалось.

double PyOS_ascii_atof(const char *nptr)

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

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

char * PyOS_stricmp(char *s1, char *s2)
Сравнение строк без учёта регистра. Функция работает почти идентично strcmp, за исключением того, что она игнорирует регистр.
char * PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
Сравнение строк без учёта регистра. Функция работает почти идентично strncmp, за исключением того, что она игнорирует регистр.