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

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

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, преобразование вывода прошло успешно, и в str было записано rv символов (исключая заключительный '\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() за исключением того, что она игнорирует регистр.