Преобразование и форматирование строк

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

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

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

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

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

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 в случае ошибки. Множество принятых строк соответствует набору строк, принятых конструктором Python float(), за исключением того, что s не должен иметь начальных или конечных пробелов. Преобразование не зависит от текущего языкового стандарта.

Если endptr — NULL, Преобразовывает всю строку. Вызывает ValueError и возвращает -1.0, если строка не является допустимым представлением числа с плавающей запятой.

Если endptr не NULL, преобразовать как можно большую часть строки и устанавливает *endptr так, чтобы он указывал на первый непреобразованный символ. Если начальный сегмент строки не является допустимым представлением числа с плавающей запятой, устанавливает *endptr так, чтобы он указывал на начало строки, вызвать ValueError и возвращает -1.0.

Если s представляет собой значение, которое слишком велико для хранения в виде числа с плавающей запятой (например, "1e500" является такой строкой на многих платформах), то если overflow_exception является NULL, возвращает Py_HUGE_VAL (с соответствующим знаком) и не устанавливайте никаких исключений. В противном случае overflow_exception должен указывать на объект исключения Python; вызвать это исключение и возвращает -1.0. В обоих случаях устанавливает *endptr так, чтобы он указывал на первый символ после преобразованного значения.

Если во время преобразования происходит какая-либо другая ошибка (например, ошибка нехватки памяти), устанавливает соответствующее исключение Python и возвращает -1.0.

Добавлено в версии 3.1.

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

Добавлено в версии 3.1.

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

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

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

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