浮點數（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 的常數運算式，表示正無窮大。

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

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" 常數。

Py_MATH_PI

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

Py_MATH_PIl

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

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。
