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

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

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

Part of the Стабильный ABI.

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

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

Part of the Стабильный ABI.

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

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

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

Part of the Стабильный ABI.

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

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

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

Смотрите также справочную страницу Unix strtoul(3).

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

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

Part of the Стабильный ABI.

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

Аналогично PyOS_strtoul(), но вместо этого возвращает значение long и LONG_MAX при переполнении.

Смотрите также справочную страницу Unix strtol(3).

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

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

Part of the Стабильный ABI.

Преобразуйте строку s в a 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)¶

Part of the Стабильный ABI.

Преобразуйте a double val в строку, используя указанные format_code, precision и flags.

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

флаги могут содержать ноль или более значений Py_DTSF_SIGN, Py_DTSF_ADD_DOT_0, или Py_DTSF_ALT, или-ed вместе:

• 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 является конечным числом, бесконечным числом или не числом, соответственно.

Возвращаемое значение является указателем на буфер с преобразованной строкой или NULL, если преобразование завершилось неудачно. Вызывающий объект отвечает за освобождение возвращаемой строки, вызывая PyMem_Free().

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

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

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

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

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