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

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

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. vsnprintf(3) справочной страницы Unix.

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

Обертки гарантируют, что str [size-1] всегда будет возвращать '\0'. Они никогда не записывают более size байт (включая конечный '\0') в строку. Обе функции требуют 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 представляет значение, которое является слишком большим, чтобы сохраниться в float (например, "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(), за исключением того, что она игнорирует регистр.