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

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

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

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

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

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

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

Выводит не более 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 и 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 strtoul(3).

Добавлена в версии 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 strtol(3).

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

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

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

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

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

Преобразует 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, объединенных через операцию OR:

• Py_DTSF_SIGN означает, что возвращаемая строка всегда должна предваряться знаком, даже если val неотрицательное.
• Py_DTSF_ADD_DOT_0 означает, что возвращаемая строка не должна выглядеть как целое число.
• Py_DTSF_ALT означает применение правил альтернативного форматирования. См. документацию для спецификатора PyOS_snprintf() '#' для получения подробной информации.

Если ptype не NULL, то значение, на которое указывает ptype, будет установлено в одно из 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(), за исключением того, что она игнорирует регистр.