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

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

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

Часть Стабильный ABI.

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

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

Часть Стабильный ABI.

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

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

Обертки гарантируют, что по возвращении str[size-1] всегда будет '\0'. Они никогда не записывают в str больше size байт (включая концевой '\0'). Обе функции требуют, чтобы str != NULL, size > 0, format != NULL и size < INT_MAX. Обратите внимание, что это означает, что не существует эквивалента C99 n = snprintf(NULL, 0, ...), который бы определял необходимый размер буфера.

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

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

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

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

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

unsigned long PyOS_strtoul(const char *str, char **ptr, int base)

Часть Стабильный ABI.

Преобразуйте начальную часть строки в str в значение unsigned long в соответствии с заданным base, которое должно находиться между 2 и 36 включительно или быть специальным значением 0.

Ведущие пробелы и регистр символов игнорируются. Если base равен нулю, он ищет ведущие 0b, 0o или 0x, чтобы определить базу. Если они отсутствуют, по умолчанию используется 10. Основание должно быть 0 или от 2 до 36 (включительно). Если ptr не является NULL, он будет содержать указатель на конец сканирования.

Если преобразованное значение выходит за пределы диапазона соответствующего возвращаемого типа, происходит ошибка диапазона (errno устанавливается в ERANGE) и возвращается ULONG_MAX. Если преобразование не может быть выполнено, возвращается 0.

См. также страницу Unix man page strtoul(3).

Added in version 3.2.

long PyOS_strtol(const char *str, char **ptr, int base)

Часть Стабильный ABI.

Преобразуйте начальную часть строки в str в значение long в соответствии с заданным base, которое должно находиться между 2 и 36 включительно или быть специальным значением 0.

То же самое, что и PyOS_strtoul(), но вместо него возвращается значение long, а при переполнении - LONG_MAX.

См. также страницу Unix man page strtol(3).

Added in version 3.2.

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

Часть Стабильный ABI.

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

Added in version 3.1.

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

Часть Стабильный ABI.

Преобразование double val в строку, используя предоставленные код_формата, точность и флаги.

код_формата должен быть одним из 'e', 'E', 'f', 'F', 'g', 'G' или 'r'. Для 'r' указанное значение прецизионности должно быть равно 0 и игнорируется. Код формата 'r' задает стандартный формат repr().

флаги могут быть нулем или более из значений 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().

Added in version 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(), за исключением того, что она игнорирует регистр.