浮點數(Floating-Point)物件

typePyFloatObject

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

PyTypeObjectPyFloat_Type
穩定 ABI 的一部分.

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

intPyFloat_Check(PyObject*p)

如果其引數是PyFloatObjectPyFloatObject 的子型別,則回傳 true。這個函式不會失敗。

intPyFloat_CheckExact(PyObject*p)

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

PyObject*PyFloat_FromString(PyObject*str)
回傳值:新的參照。穩定 ABI 的一部分.

建立一個基於字串值strPyFloatObject 物件,失敗時回傳NULL

PyObject*PyFloat_FromDouble(doublev)
回傳值:新的參照。穩定 ABI 的一部分.

建立一個來自vPyFloatObject 物件,失敗時回傳NULL

doublePyFloat_AsDouble(PyObject*pyfloat)
穩定 ABI 的一部分.

回傳pyfloat 內容的 Cdouble 表示形式。如果pyfloat 不是 Python 浮點數物件,但具有__float__() 方法,則會先呼叫此方法將pyfloat 轉換為浮點數。如果未定義__float__(),則會用後備方法__index__()。此方法在失敗時回傳-1.0,因此應該呼叫PyErr_Occurred() 來檢查錯誤。

在 3.8 版的變更:請使用__index__()(如果可用)。

doublePyFloat_AS_DOUBLE(PyObject*pyfloat)

回傳pyfloat 內容的 Cdouble 表示形式,但不進行錯誤檢查。

PyObject*PyFloat_GetInfo(void)
回傳值:新的參照。穩定 ABI 的一部分.

回傳一個 structseq 實例,其中包含有關浮點數的精度、最小值和最大值的資訊。它是對標頭檔float.h 的簡單封裝。

doublePyFloat_GetMax()
穩定 ABI 的一部分.

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

doublePyFloat_GetMin()
穩定 ABI 的一部分.

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

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

在大多數平台上,這相當於returnPyFloat_FromDouble(NAN)

Py_RETURN_INF(sign)

根據sign 的正負號,從函式回傳math.inf-math.inf

在大多數平台上,這相當於以下內容:

returnPyFloat_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

打包和解包函式

打包和解包函式提供了一種有效的跨平台方式,來將浮點數值儲存為位元組字串。打包例程從 Cdouble 產生位元組字串,而解包例程則從這樣的位元組字串產生 Cdouble。後綴(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+1p+3p+6p+7),則用非零值;如果你想要大端序格式(指數在最前,位於p),則用零。可以使用PY_BIG_ENDIAN 常數來使用原生端序:在大端序處理器上它等於1,在小端序處理器上它等於0

回傳值:如果一切正常則為0,如果發生錯誤則為-1(並且會設定一個例外,最有可能是OverflowError)。

在非 IEEE 平台上有兩個問題:

  • 如果x 是 NaN 或無窮大,則這樣做是未定義的。

  • -0.0+0.0 會產生同樣的位元組字串。

intPyFloat_Pack2(doublex,char*p,intle)

將 C double 打包為 IEEE 754 binary16 半精度格式。

intPyFloat_Pack4(doublex,char*p,intle)

將 C double 打包為 IEEE 754 binary32 單精度格式。

intPyFloat_Pack8(doublex,char*p,intle)

將 C double 打包為 IEEE 754 binary64 雙精度格式。

解包函式

解包例程會從p 開始讀取 2、4 或 8 位元組。le 是一個int 引數,如果位元組字串為小端序格式(指數在最後,位於p+1p+3p+6p+7),則用非零值;如果為大端序格式(指數在最前,位於p),則用零。可以使用PY_BIG_ENDIAN 常數來使用原生端序:在大端序處理器上它等於1,在小端序處理器上它等於0

回傳值:解包後的 double。發生錯誤時,這是-1.0PyErr_Occurred() 為 true(並且會設置一個例外,最有可能是OverflowError)。

請注意,在非 IEEE 平台上,這將拒絕解包會表示為 NaN 或無窮大的位元組字串。

doublePyFloat_Unpack2(constchar*p,intle)

將 IEEE 754 binary16 半精度格式解包為 C double。

doublePyFloat_Unpack4(constchar*p,intle)

將 IEEE 754 binary32 單精度格式解包為 C double。

doublePyFloat_Unpack8(constchar*p,intle)

將 IEEE 754 binary64 雙精度格式解包為 C double。