# 浮点数对象

type PyFloatObject

  这个 `PyObject` 的子类型代表一个 Python 浮点数对象。

PyTypeObject PyFloat_Type
  属于 稳定 ABI.

  这个 `PyTypeObject` 实例代表 Python 浮点数类型。这与 Python 层面的 `float` 是同一个对象。

int PyFloat_Check(PyObject *p)

  如果它的参数是一个 `PyFloatObject` 或者 `PyFloatObject` 的子类型则返回真值。 此函数总是会成功执行。

int PyFloat_CheckExact(PyObject *p)

  如果它的参数是一个 `PyFloatObject` 但不是 `PyFloatObject` 的子类型则返回真值。 此函数总是会成功执行。

PyObject *PyFloat_FromString(PyObject *str)
  返回值：新的引用。 属于 稳定 ABI.

  根据字符串 str 的值创建一个 `PyFloatObject`，失败时返回 `NULL`。

PyObject *PyFloat_FromDouble(double v)
  返回值：新的引用。 属于 稳定 ABI.

  根据 v 创建一个 `PyFloatObject` 对象，失败时返回 `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 的精度、最小值和最大值的信息。它是头文件 `float.h` 的一个简单包装。

double PyFloat_GetMax()
  属于 稳定 ABI.

  返回 C double 形式的最大可表示有限浮点数 DBL_MAX。

double PyFloat_GetMin()
  属于 稳定 ABI.

  返回 C double 形式的最小正规化正浮点数 DBL_MIN。

Py_INFINITY

  这个宏会扩展为一个 double 类型的常量表达式，它代表正无穷大。

  在大多数平台上，这等价于 C11 标准 `<math.h>` 头文件中的 `INFINITY` 宏。

Py_NAN

  这个宏会扩展为一个 double 类型的常量表达式，它代表一个 quiet not-a-number (qNaN) 值。

  在大多数平台上，这等价于 C11 标准 `<math.h>` 头文件中的 `NAN` 宏。

Py_HUGE_VAL

  等价于 `INFINITY`。

  自 3.14 版本弃用: 此宏已处于 soft deprecated 状态。

Py_MATH_E

  `math.e` 常量的定义（基于 double 类型的精度）。

Py_MATH_El

  高精度 (long double) 的 `e` 常量定义。

Py_MATH_PI

  `math.pi` 常量的定义（基于 double 类型的精度）。

Py_MATH_PIl

  高精度 (long double) 的 `pi` 常量定义。

Py_MATH_TAU

  `math.tau` 常量的定义（基于 double 类型的精度）。

  Added in version 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)

  如果给定的浮点数 X 为有限值，即为规格数、非规格数或零，而不是无穷大或 NaN 则返回 `1`。否则返回 `0`。

  自 3.14 版本弃用: 该宏已处于 soft deprecated 状态。请改用 `isfinite`。

Py_IS_INFINITY(X)

  如果给定的浮点数 X 为正或负无穷大则返回 `1`。否则返回 `0`。

  自 3.14 版本弃用: 该宏已处于 soft deprecated 状态。请改用 `isinf`。

Py_IS_NAN(X)

  如果给定的浮点数 X 为非数字 (NaN) 值则返回 `1`。否则返回 `0`。

  自 3.14 版本弃用: 该宏已处于 soft deprecated 状态。请改用 `isnan`。

## 打包与解包函数

打包与解包函数提供了独立于平台的高效方式来将浮点数值存储为字节串。Pack 例程根据 C double 产生字节串，而 Unpack 例程根据这样的字节串产生 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 的字节串执行解包将会引发一个异常。

请注意 NaN 类型在 IEEE 平台上可能不会被保留（带信号的 NaN 变为静默的 NaN），例如在 32 位模式的 x86 系统上。

在具有比 IEEE 754 所支持的更高精度，或更大动态范围的非 IEEE 平台上，不是所有的值都能被打包；在具有更低精度，或更小动态范围的非 IEEE 平台上，则不是所有的值都能被解包。在这种情况下发生的事情有一部分将是偶然的（无奈）。

Added in version 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()` 为真值 (并且会设置一个异常，最大可能为 `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。