# 浮點數（Floating-Point）物件

type PyFloatObject

  這個 `PyObject` 的子型別代表一個 Python 浮點數物件。

PyTypeObject PyFloat_Type
  為 穩定 ABI 的一部分.

  這個 `PyTypeObject` 的實例代表 Python 浮點數型別。這與 Python 層中的 `float` 物件相同。

int PyFloat_Check(PyObject *p)

  如果其引數是 `PyFloatObject` 或 `PyFloatObject` 的子型別，則回傳 true。這個函式不會失敗。

int PyFloat_CheckExact(PyObject *p)

  如果其引數是 `PyFloatObject`，但不是 `PyFloatObject` 的子型別，則回傳 true。這個函式不會失敗。

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.h` 的簡單封裝。

double PyFloat_GetMax()
  為 穩定 ABI 的一部分.

  將可表示的最大有限浮點數 DBL_MAX 作為 C double 回傳。

double PyFloat_GetMin()
  為 穩定 ABI 的一部分.

  將最小的正規化浮點數 DBL_MIN 作為 C double 回傳。

Py_INFINITY

  這個巨集會展開為一型別為 double 的常數運算式，表示正無窮大。

  It is equivalent to the `INFINITY` macro from the C11 standard `<math.h>` header.

  在 3.15 版之後被棄用: 這個巨集已被軟性棄用。

Py_NAN

  這個巨集會展開為一型別為 double 的常數運算式，表示安靜型 NaN (qNaN) 值。

  在大多數平台上，這相當於 C11 標準 `<math.h>` 標頭檔中的 `NAN` 巨集。

Py_HUGE_VAL

  與 `INFINITY` 等價。

  在 3.14 版之後被棄用: 這個巨集已被軟性棄用。

Py_MATH_E

  `math.e` 常數的定義（對 double 型別而言是準確的）。

Py_MATH_El

  高精度（long double）定義的 `e` 常數。

  自從版本 3.15 後不推薦使用，將會自版本 3.20 中移除。.

Py_MATH_PI

  `math.pi` 常數的定義（對 double 型別而言是準確的）。

Py_MATH_PIl

  高精度（long double）定義的 `pi` 常數。

  自從版本 3.15 後不推薦使用，將會自版本 3.20 中移除。.

Py_MATH_TAU

  `math.tau` 常數的定義（對 double 型別而言是準確的）。

  在 3.6 版被加入.

Py_RETURN_NAN

  從函式回傳 `math.nan`。

  在大多數平台上，這相當於 `return PyFloat_FromDouble(NAN)`。

Py_RETURN_INF(sign)

  根據 sign 的正負號，從函式回傳 `math.inf` 或 `-math.inf`。

  在大多數平台上，這相當於以下內容：

      return PyFloat_FromDouble(copysign(INFINITY, sign));

Py_IS_FINITE(X)

  如果給定的浮點數 X 是有限的（即為正規數 (normal)、次正規數 (subnormal) 或零，但不是無窮大或 NaN），則回傳 `1`。否則回傳 `0`。

  在 3.14 版之後被棄用: 此巨集已被軟性棄用。請改用 `isfinite`。

Py_IS_INFINITY(X)

  如果給定的浮點數 X 是正無窮大或負無窮大，則回傳 `1`。否則回傳 `0`。

  在 3.14 版之後被棄用: 此巨集已被軟性棄用。請改用 `isinf`。

Py_IS_NAN(X)

  如果給定的浮點數 X 是非數值 (NaN)，則回傳 `1`。否則回傳 `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 (signaling NaN)」會變成「安靜型 NaN (quiet NaN)」），例如在 32 位元模式的 x86 系統上。

在非 IEEE 平台上，如果精度更高或動態範圍比 IEEE 754 支援的更大，則無法打包所有值；在非 IEEE 平台上，如果精度較低或動態範圍較小，則無法解包所有值。在這種案例下發生的情況在某種程度上是偶然的（唉）。

在 3.11 版被加入.

### 打包函式

打包例程會從 p 開始寫入 2、4 或 8 位元組。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 雙精度格式。

### 解包函式

解包例程會從 p 開始讀取 2、4 或 8 位元組。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。