Объекты с плавающей точкой

type PyFloatObject: Этот подтип PyObject представляет объект Python с плавающей точкой.

PyTypeObject PyFloat_Type: Часть стабильного ABI.
Этот экземпляр PyTypeObject представляет тип Python с плавающей точкой. Это тот же объект, что и float на уровне Python.

int PyFloat_Check(PyObject *p): Возвращает true, если аргумент является PyFloatObject или подтипом PyFloatObject. Эта функция всегда завершается успешно.

int PyFloat_CheckExact(PyObject *p): Возвращает true, если аргумент является PyFloatObject, но не его подтипом PyFloatObject. Эта функция всегда завершается успешно.

PyObject *PyFloat_FromString(PyObject *str): Возвращаемое значение: новая ссылка. Часть стабильного ABI.
Создаёт объект PyFloatObject на основе строкового значения в str или возвращает NULL в случае ошибки.

PyObject *PyFloat_FromDouble(double v): Возвращаемое значение: новая ссылка. Часть стабильного ABI.
Создаёт объект PyFloatObject из v или возвращает NULL в случае ошибки.

double PyFloat_AsDouble(PyObject *pyfloat): Часть стабильного ABI.
Возвращает представление содержимого pyfloat в виде C-типа double. Если pyfloat не является объектом Python с плавающей точкой, но имеет метод __float__(), этот метод сначала будет вызван для преобразования pyfloat в число с плавающей точкой. Если __float__() не определён, вместо него используется __index__(). В случае ошибки этот метод возвращает -1.0, поэтому для проверки ошибок следует вызвать PyErr_Occurred().

Изменено в версии 3.8: Используется __index__(), если он доступен.

double PyFloat_AS_DOUBLE(PyObject *pyfloat): Возвращает представление содержимого pyfloat в виде C-типа double, не выполняя проверку ошибок.

PyObject *PyFloat_GetInfo(void): Возвращаемое значение: новая ссылка. Часть стабильного ABI.
Возвращает экземпляр structseq, содержащий сведения о точности, минимальном и максимальном значениях числа с плавающей точкой. Это тонкая обёртка над заголовочным файлом float.h.

double PyFloat_GetMax(): Часть стабильного ABI.
Возвращает максимальное представимое конечное число с плавающей точкой DBL_MAX как значение C-типа double.

double PyFloat_GetMin(): Часть стабильного ABI.
Возвращает минимальное нормализованное положительное число с плавающей точкой DBL_MIN как значение C-типа double.

Py_INFINITY

Этот макрос раскрывается в константное выражение типа double, представляющее положительную бесконечность.

На большинстве платформ он эквивалентен макросу INFINITY из заголовочного файла <math.h> стандарта C11.

Py_NAN

Этот макрос раскрывается в константное выражение типа double, представляющее тихое значение «не число» (qNaN).

На большинстве платформ он эквивалентен макросу NAN из заголовочного файла <math.h> стандарта C11.

Py_HUGE_VAL: Эквивалентен INFINITY.

Устарел с версии 3.14: Макрос имеет статус мягко устаревшего.

Py_MATH_E: Определение константы math.e (точное для типа double).

Py_MATH_El: Высокоточное определение константы e (long double).

Py_MATH_PI: Определение константы math.pi (точное для типа double).

Py_MATH_PIl: Высокоточное определение константы pi (long double).

Py_MATH_TAU: Определение константы math.tau (точное для типа double).

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

Py_RETURN_NAN

Возвращает math.nan из функции.

На большинстве платформ это эквивалентно return PyFloat_FromDouble(NAN).

Py_RETURN_INF(sign)

Возвращает из функции math.inf или -math.inf в зависимости от знака sign.

На большинстве платформ это эквивалентно следующему:

return PyFloat_FromDouble(copysign(INFINITY, sign));

Py_IS_FINITE(X): Возвращает 1, если заданное число с плавающей точкой X является конечным, то есть нормальным, субнормальным или нулём, но не бесконечностью и не NaN. В противном случае возвращает 0.

Устарел с версии 3.14: Макрос имеет статус мягко устаревшего. Вместо него используйте isfinite.

Py_IS_INFINITY(X): Возвращает 1, если заданное число с плавающей точкой X является положительной или отрицательной бесконечностью. В противном случае возвращает 0.

Устарел с версии 3.14: Макрос имеет статус мягко устаревшего. Вместо него используйте isinf.

Py_IS_NAN(X): Возвращает 1, если заданное число с плавающей точкой X является значением «не число» (NaN). В противном случае возвращает 0.

Устарел с версии 3.14: Макрос имеет статус мягко устаревшего. Вместо него используйте isnan.

Функции упаковки и распаковки

Функции упаковки и распаковки позволяют эффективно и независимо от платформы хранить значения с плавающей точкой в виде байтовых строк. Функции упаковки преобразуют значение C-типа double в байтовую строку, а функции распаковки преобразуют такую байтовую строку в значение C-типа double. Суффикс (2, 4 или 8) указывает количество байтов в байтовой строке.

На платформах, использующих, судя по всему, форматы IEEE 754, эти функции работают путём копирования битов. На других платформах 2-байтовый формат идентичен формату IEEE 754 binary16 с половинной точностью, 4-байтовый формат (32-разрядный) идентичен формату IEEE 754 binary32 с одинарной точностью, а 8-байтовый формат — формату IEEE 754 binary64 с двойной точностью. Однако упаковка INF и NaN (если такие значения поддерживаются платформой) обрабатывается некорректно, и попытка распаковать байтовую строку, содержащую IEEE INF или NaN, вызовет исключение.

Обратите внимание, что на платформах IEEE тип NaN может не сохраняться (сигнальные NaN становятся тихими NaN), например, в 32-разрядном режиме на системах x86.

На платформах, не соответствующих IEEE, с большей точностью или более широким динамическим диапазоном, чем предусмотрено IEEE 754, упаковать удаётся не все значения; на платформах, не соответствующих IEEE, с меньшей точностью или более узким динамическим диапазоном удаётся распаковать не все значения. Поведение в таких случаях отчасти определяется случайными обстоятельствами (увы).

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

Функции упаковки

Функции упаковки записывают 2, 4 или 8 байтов, начиная с p. le — аргумент типа int, который должен быть ненулевым, если байтовая строка должна иметь порядок байтов от младшего к старшему (экспонента в конце, в p+1, p+3 или p+6 и p+7), и нулевым, если нужен порядок байтов от старшего к младшему (экспонента в начале, в p). Для использования порядка байтов, принятого на текущей платформе, можно использовать константу PY_BIG_ENDIAN: на процессоре с порядком байтов от старшего к младшему она равна 1, а на процессоре с порядком байтов от младшего к старшему — 0.

Возвращаемое значение: 0 в случае успеха, -1 в случае ошибки (при этом устанавливается исключение, скорее всего OverflowError).

На платформах, не соответствующих IEEE, есть две проблемы:

Поведение не определено, если x — NaN или бесконечность.
-0.0 и +0.0 создают одинаковую байтовую строку.

int PyFloat_Pack2(double x, char *p, int le): Упаковывает значение C-типа double в формат IEEE 754 binary16 с половинной точностью.

int PyFloat_Pack4(double x, char *p, int le): Упаковывает значение C-типа double в формат IEEE 754 binary32 с одинарной точностью.

int PyFloat_Pack8(double x, char *p, int le): Упаковывает значение C-типа double в формат IEEE 754 binary64 с двойной точностью.

Функции распаковки

Функции распаковки считывают 2, 4 или 8 байтов, начиная с p. le — аргумент типа int, который должен быть ненулевым, если байтовая строка имеет порядок байтов от младшего к старшему (экспонента в конце, в p+1, p+3 или p+6 и p+7), и нулевым, если порядок байтов от старшего к младшему (экспонента в начале, в p). Для использования порядка байтов, принятого на текущей платформе, можно использовать константу PY_BIG_ENDIAN: на процессоре с порядком байтов от старшего к младшему она равна 1, а на процессоре с порядком байтов от младшего к старшему — 0.

Возвращаемое значение: распакованное значение double. В случае ошибки возвращается -1.0, а PyErr_Occurred() имеет значение true (при этом устанавливается исключение, скорее всего OverflowError).

Обратите внимание, что на платформе, не соответствующей IEEE, эта функция откажется распаковывать байтовую строку, представляющую NaN или бесконечность.

double PyFloat_Unpack2(const char *p, int le): Распаковывает формат IEEE 754 binary16 с половинной точностью в значение C-типа double.

double PyFloat_Unpack4(const char *p, int le): Распаковывает формат IEEE 754 binary32 с одинарной точностью в значение C-типа double.

double PyFloat_Unpack8(const char *p, int le): Распаковывает формат IEEE 754 binary64 с двойной точностью в значение C-типа double.