اشیاء ممیز شناور

type PyFloatObject

این زیرنوع از PyObject نمایانگر یک شیء ممیز شناور پایتون است.

PyTypeObject PyFloat_Type
قسمتی از ABI پایدار.

این نمونه از PyTypeObject نوع ممیز شناور پایتون را نشان می‌دهد. این همان شیء float در لایه‌ی پایتون است.

int PyFloat_Check(PyObject *p)

اگر آرگومان آن یک PyFloatObject یا زیرنوعی از PyFloatObject باشد، مقدار درست را برمی‌گرداند. این تابع همیشه با موفقیت انجام می‌شود.

int PyFloat_CheckExact(PyObject *p)

اگر آرگومان آن یک PyFloatObject باشد، اما زیرنوعی از PyFloatObject نباشد، مقدار true برمی‌گرداند. این تابع همیشه موفق می‌شود.

PyObject *PyFloat_FromString(PyObject *str)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

ایجاد یک شیء PyFloatObject بر اساس مقدار رشته در str، یا NULL در صورت شکست.

PyObject *PyFloat_FromDouble(double v)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک شیء PyFloatObject از v می‌سازد، یا در صورت شکست NULL.

double PyFloat_AsDouble(PyObject *pyfloat)
قسمتی از ABI پایدار.

یک نمایش double در C از محتویات pyfloat برمی‌گرداند. اگر pyfloat یک شیء ممیز شناور پایتون نباشد اما متد __float__() را داشته باشد، این متد ابتدا برای تبدیل pyfloat به یک عدد ممیز شناور فراخوانی می‌شود. اگر __float__() تعریف‌نشده باشد، به __index__() بازمی‌گردد. این متد در صورت شکست -1.0 را برمی‌گرداند، بنابراین برای بررسی خطاها باید PyErr_Occurred() را فراخوانی کنید.

تغییر یافته در نسخه‌ی 3.8: در صورت وجود، از __index__() استفاده کنید.

double PyFloat_AS_DOUBLE(PyObject *pyfloat)

نمایش C double از محتویات pyfloat را برمی‌گرداند، اما بدون بررسی خطا.

PyObject *PyFloat_GetInfo(void)
مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

یک نمونه از دنباله ساختاری برمی‌گرداند که اطلاعاتی درباره‌ی دقت و مقادیر کمینه و بیشینه‌ی یک عدد ممیز شناور در بر دارد. این یک دربرگیرنده‌ی نازک حول پرونده‌ی سرآیند float.h است.

double PyFloat_GetMax()
قسمتی از ABI پایدار.

بزرگ‌ترین عدد ممیز شناور محدود قابل نمایش DBL_MAX را به‌صورت double در C برمی‌گرداند.

double PyFloat_GetMin()
قسمتی از ABI پایدار.

کمترین عدد اعشاری مثبت نرمال‌شده DBL_MIN را به‌صورت double در C برمی‌گرداند.

Py_INFINITY

این ماکرو به یک عبارت ثابت از نوع double بسط می‌یابد که بی‌نهایت مثبت را نشان می‌دهد.

در بیشتر پلتفرم‌ها، این معادل ماکروی INFINITY از سرآیند <math.h> استاندارد C11 است.

Py_NAN

این ماکرو به عبارت ثابتی از نوع double بسط می‌یابد که نشان‌دهنده‌ی مقدار عدد-نیست ساکت (qNaN) است.

در بیشتر پلتفرم‌ها، این معادل ماکروی NAN از سرآیند <math.h> استاندارد C11 است.

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

تعریف ثابت 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)

اگر عدد ممیز شناور داده‌شده X متناهی باشد، یعنی نرمال، زیرنرمال یا صفر باشد، اما بی‌نهایت یا NaN نباشد، 1 را برمی‌گرداند. در غیر این صورت 0 را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.14: این ماکرو نرم‌منسوخ (soft deprecated) است. به‌جای آن از isfinite استفاده کنید.

Py_IS_INFINITY(X)

اگر عدد ممیز شناورِ داده‌شده‌ی X بی‌نهایت مثبت یا منفی باشد، 1 را برمی‌گرداند. در غیر این صورت 0 را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.14: این ماکرو منسوخ نرم است. به‌جای آن از isinf استفاده کنید.

Py_IS_NAN(X)

اگر عدد ممیز شناورِ داده‌شده‌ی X مقداری غیرعددی (NaN) باشد، 1 را برمی‌گرداند. در غیر این صورت 0 را برمی‌گرداند.

منسوخ شده از نسخه‌ی 3.14: این ماکرو soft deprecated است. به‌جای آن از isnan استفاده کنید.

توابع بسته‌بندی و باز کردن بسته‌بندی

توابع pack و unpack راهی کارآمد و مستقل از پلتفرم برای ذخیره‌سازی مقادیر ممیز شناور به‌صورت رشته‌های بایتی فراهم می‌کنند. روال‌های Pack از یک double در C یک رشته بایتی تولید می‌کنند و روال‌های Unpack از چنین رشته بایتی، یک double در C تولید می‌کنند. پسوند (۲، ۴ یا ۸) تعداد بایت‌های رشته بایتی را مشخص می‌کند.

در پلتفرم‌هایی که به نظر می‌رسد از قالب‌های IEEE 754 استفاده می‌کنند، این توابع با کپی کردن بیت‌ها کار می‌کنند. در پلتفرم‌های دیگر، قالب ۲ بایتی با قالب دقت نصف binary16 در IEEE 754 یکسان است، قالب ۴ بایتی (۳۲ بیتی) با قالب دقت منفرد binary32 در IEEE 754 یکسان است و قالب ۸ بایتی با قالب دقت مضاعف binary64 در IEEE 754 یکسان است؛ هرچند بسته‌بندی مقادیر INF و NaN (اگر چنین مقادیری در پلتفرم وجود داشته باشند) به‌درستی مدیریت نمی‌شود و تلاش برای واگشایی رشته بایتی حاوی INF یا NaN مطابق با IEEE، منجر به ایجاد استثنا می‌شود.

توجه داشته باشید که نوع NaN ممکن است روی سکوهای IEEE حفظ نشود (NaNهای سیگنال‌دهنده به NaNهای خاموش (quiet NaN) تبدیل می‌شوند)، برای مثال روی سیستم‌های x86 در حالت ۳۲ بیتی.

در پلتفرم‌های غیر IEEE که دقتی بیشتر از آنچه IEEE 754 از آن پشتیبانی می‌کند دارند، یا گستره پویایی بزرگ‌تری دارند، نمی‌توان همه مقادیر را بسته‌بندی کرد؛ در پلتفرم‌های غیر IEEE با دقت کمتر، یا گستره پویایی کوچک‌تر، نمی‌توان همه مقادیر را واگشایی کرد. آنچه در چنین مواردی رخ می‌دهد تا حدی اتفاقی است (متأسفانه).

اضافه شده در نسخه‌ی 3.11.

توابع بسته‌بندی

روال‌های بسته‌بندی ۲، ۴ یا ۸ بایت را با شروع از 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 را به قالب binary16 با دقت نصف IEEE 754 بسته‌بندی می‌کند.

int PyFloat_Pack4(double x, char *p, int le)

یک ممیز شناور با دقت مضاعف در C را به قالب IEEE 754 binary32 با دقت منفرد بسته‌بندی می‌کند.

int PyFloat_Pack8(double x, char *p, int le)

یک double زبان C را به قالب دقت مضاعف binary64 استاندارد IEEE 754 بسته‌بندی می‌کند.

توابع واگشایی

روال‌های واگشایی ۲، ۴ یا ۸ بایت را با شروع از p می‌خوانند. le یک آرگومان int است؛ اگر رشته بایتی در قالب کوچک‌اندیان باشد، ناصفر است (نما در انتها، در p+1، p+3 یا p+6 و p+7)، و اگر بزرگ‌اندیان باشد، صفر است (نما در ابتدا، در p). می‌توان ثابت PY_BIG_ENDIAN را برای بهره‌گیری از اندیان بومی به کار برد: این ثابت روی پردازنده‌ی بزرگ‌اندیان برابر 1، یا روی پردازنده‌ی کوچک‌اندیان برابر 0 است.

مقدار بازگشتی: ممیز شناور با دقت مضاعفِ واگشایی‌شده. در صورت خطا، این مقدار -1.0 است و PyErr_Occurred() درست است (و استثنایی تنظیم‌شده است که به احتمال زیاد OverflowError است).

توجه داشته باشید که روی یک پلتفرم غیر IEEE، این از واگشایی کردن رشته‌ی بایتی که نمایانگر NaN یا بی‌نهایت است، خودداری خواهد کرد.

double PyFloat_Unpack2(const char *p, int le)

قالب IEEE 754 binary16 با دقت نصف را به‌صورت یک double در C واگشایی می‌کند.

double PyFloat_Unpack4(const char *p, int le)

واگشایی کردن قالب دقت منفرد binary32 از IEEE 754 به‌صورت double در C.

double PyFloat_Unpack8(const char *p, int le)

قالب دقت مضاعف binary64 در استاندارد IEEE 754 را به‌صورت یک double در C واگشایی می‌کند.