fenv(3)

الاسم
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept, fegetenv, fegetround, feholdexcept, fesetround, fesetenv, feupdateenv, feenableexcept, fedisableexcept, fegetexcept - تقريب ومعالجة استثناءات الفاصلة العائمة

المكتبة
مكتبة الرياضيات (libm، -lm)

موجز
#include <fenv.h>

int feclearexcept(int excepts);
int fegetexceptflag(fexcept_t *flagp, int excepts);
int feraiseexcept(int excepts);
int fesetexceptflag(const fexcept_t *flagp, int excepts);
int fetestexcept(int excepts);

int fegetround(void);
int fesetround(int rounding_mode);

int fegetenv(fenv_t *envp);
int feholdexcept(fenv_t *envp);
int fesetenv(const fenv_t *envp);
int feupdateenv(const fenv_t *envp);

الوصف
عُرّفت هذه الدوال الإحدى عشرة في C99، وتصف معالجة تقريب واستثناءات الفاصلة العائمة (فيضان، قسمة على صفر، إلخ).

  الاستثناءات
يحدث استثناء القسمة على صفر عندما تُنتج عملية على أعداد محدودة اللانهاية كإجابة دقيقة.

يحدث استثناء الفيضان عندما يجب تمثيل نتيجة كرقم فاصلة عائمة، لكن قيمتها المطلقة أكبر (بكثير) من أكبر رقم فاصلة عائمة (محدود) قابل للتمثيل.

يحدث استثناء النقصان عندما يجب تمثيل نتيجة كرقم فاصلة عائمة، لكن قيمتها المطلقة أصغر من أصغر رقم فاصلة عائمة موجب معياري (وستفقد دقة كبيرة عند تمثيلها كرقم غير معياري).

يحدث استثناء عدم الدقة عندما لا تساوي النتيجة المقربة لعملية ما النتيجة ذات الدقة اللانهائية. قد يحدث كلما حدث فيضان أو نقصان.

يحدث استثناء غير الصالح عندما لا توجد نتيجة محددة جيدًا لعملية ما، كما في 0/0 أو لانهاية - لانهاية أو sqrt(-1).

  معالجة الاستثناءات
تُُمثّل الاستثناءات بطريقتين: كبتة واحدة (استثناء موجود/غائب)، وتتوافق هذه البتات بطريقة محددة بالتنفيذ مع مواضع بتات في عدد صحيح، وأيضًا كهيكل معتم قد يحتوي على معلومات إضافية عن الاستثناء (ربما عنوان الكود حيث حدث).

يُعرّف كل من الأكرو FE_DIVBYZERO وFE_INEXACT وFE_INVALID وFE_OVERFLOW وFE_UNDERFLOW عندما يدعم التنفيذ معالجة الاستثناء المقابل، وإذا كان الأمر كذلك، يُعرّف البتة (البتات) المقابلة، بحيث يمكن استدعاء دوال معالجة الاستثناءات، على سبيل المثال، باستخدام المعامل الصحيح FE_OVERFLOW|FE_UNDERFLOW. قد تُدعم استثناءات أخرى. الأكرو FE_ALL_EXCEPT هو OR البتوي لجميع البتات المقابلة للاستثناءات المدعومة.

تمسح الدالة feclearexcept() الاستثناءات المدعومة الممثلة بالبتات في معاملها.

تخزن الدالة fegetexceptflag() تمثيلًا لحالة أعلام الاستثناء الممثلة بالمعامل excepts في الكائن المعتم *flagp.

تثير الدالة feraiseexcept() الاستثناءات المدعومة الممثلة بالبتات في excepts.

تضبط الدالة fesetexceptflag() الحالة الكاملة للاستثناءات الممثلة بـ excepts إلى القيمة *flagp. يجب أن تكون هذه القيمة قد حُصل عليها باستدعاء سابق لـ fegetexceptflag() بمعامل أخير احتوى على جميع البتات في excepts.

تُرجع الدالة fetestexcept() كلمة تُضبط فيها البتات التي ضُبطت في المعامل excepts والتي يكون الاستثناء المقابل مضبوطًا حاليًا لها.

  وضع التقريب
يحدد وضع التقريب كيفية معالجة نتيجة عمليات الفاصلة العائمة عندما لا يمكن تمثيل النتيجة بدقة في المعنِّي. قد تُوفَّر أوضاع تقريب مختلفة: التقريب إلى الأقرب (المبدئي)، التقريب لأعلى (باتجاه اللانهاية الموجبة)، التقريب لأسفل (باتجاه اللانهاية السالبة)، والتقريب نحو الصفر.

يُعرَّف كل من وحدات الماكرو FE_TONEAREST وFE_UPWARD وFE_DOWNWARD وFE_TOWARDZERO عندما يدعم التطبيق الحصول على اتجاه التقريب المقابل وتعيينه.

تُرجع الدالة fegetround() وحدة الماكرو المقابلة لوضع التقريب الحالي.

تضبط الدالة fesetround() وضع التقريب كما هو محدد بواسطة معاملها وتُرجع صفرًا عند نجاحها.

يحدد C99 وPOSIX.1-2008 معرّفًا، FLT_ROUNDS، مُعرَّفًا في <float.h>، والذي يشير إلى سلوك التقريب المُعرَّف بالتطبيق لجمع الفاصلة العائمة. لهذا المعرّف إحدى القيم التالية:

-1  وضع التقريب غير قابل للتحديد.

0   التقريب نحو 0.

1   التقريب نحو أقرب رقم.

2   التقريب نحو اللانهاية الموجبة.

3   التقريب نحو اللانهاية السالبة.

تمثل القيم الأخرى أوضاع تقريب غير قياسية تعتمد على الآلة.

يجب أن تعكس قيمة FLT_ROUNDS وضع التقريب الحالي كما ضُبط بواسطة fesetround() (ولكن انظر الأخطاء).

  بيئة الفاصلة العائمة
يمكن معالجة بيئة الفاصلة العائمة بأكملها، بما في ذلك أوضاع التحكم وأعلام الحالة، ككائن واحد غير شفاف، من النوع fenv_t. يُشار إلى البيئة المبدئية بواسطة FE_DFL_ENV (من النوع const fenv_t *). هذه هي البيئة المُعدَّة عند بدء البرنامج وهي مُعرَّفة بواسطة ISO C لتكون ذات تقريب إلى الأقرب، وجميع الاستثناءات ممسوحة، ووضع غير متوقف (استمرار عند الاستثناءات).

تحفظ الدالة fegetenv() بيئة الفاصلة العائمة الحالية في الكائن *envp.

تفعل الدالة feholdexcept() الشيء نفسه، ثم تمسح جميع أعلام الاستثناءات، وتضبط وضعًا غير متوقف (استمرار عند الاستثناءات)، إن كان متاحًا. تُرجع صفرًا عند النجاح.

تستعيد الدالة fesetenv() بيئة الفاصلة العائمة من الكائن *envp. يجب أن يكون هذا الكائن معروفًا بأنه صالح، على سبيل المثال، نتيجة استدعاء لـ fegetenv() أو feholdexcept() أو مساويًا لـ FE_DFL_ENV. لا يُثير هذا الاستدعاء استثناءات.

تُثبِّت الدالة feupdateenv() بيئة الفاصلة العائمة الممثلة بالكائن *envp، باستثناء أن الاستثناءات المُثارة حاليًا لا تُمحى. بعد استدعاء هذه الدالة، ستكون الاستثناءات المُثارة هي OR بتاتي لتلك المُعيَّنة سابقًا مع تلك الموجودة في *envp. كما في السابق، يجب أن يكون الكائن *envp معروفًا بأنه صالح.

قيمة الإرجاع
تُرجع هذه الدوال صفرًا عند النجاح وقيمة غير صفرية إذا حدث خطأ.

السمات
للاطلاع على شرح للمصطلحات المستخدمة في هذا القسم، انظر attributes(7).
الواجهة | السمة | القيمة
feclearexcept(), fegetexceptflag(), feraiseexcept(), fesetexceptflag(), fetestexcept(), fegetround(), fesetround(), fegetenv(), feholdexcept(), fesetenv(), feupdateenv(), feenableexcept(), fedisableexcept(), fegetexcept() | سلامة الخيوط | MT-Safe

المعايير
C11، POSIX.1-2008، IEC 60559 (IEC 559:1989)، ANSI/IEEE 854.

التاريخ
C99, POSIX.1-2001. glibc 2.1.

ملاحظات

  ملاحظات glibc
إن أمكن، تُعرِّف مكتبة GNU C كلية FE_NOMASK_ENV التي تمثل بيئة يُسبب فيها كل استثناء مرفوع حدوث فخ. يمكنك اختبار هذه الكلية باستخدام #ifdef. تُعرف فقط إذا عُرفت _GNU_SOURCE. لا يُعرِّف معيار C99 طريقة لتعيين البتات الفردية في قناع النقطة العائمة، على سبيل المثال، للفخ على أعلام محددة. منذ glibc 2.2، تدعم glibc الدالتين feenableexcept() و fedisableexcept() لتعيين فخاخ النقطة العائمة الفردية، و fegetexcept() لاستعلام الحالة.

#define _GNU_SOURCE         /* انظر feature_test_macros(7) */
#include <fenv.h>

int feenableexcept(int excepts);
int fedisableexcept(int excepts);
int fegetexcept(void);

تُفعِّل (تُعطِّل) الدالتان feenableexcept() و fedisableexcept() الفخاخ لكل استثناء ممثل بـ excepts وتُعيدان المجموعة السابقة من الاستثناءات المفعلة عند النجاح، و -1 بخلاف ذلك. تُعيد الدالة fegetexcept() مجموعة جميع الاستثناءات المفعلة حالياً.

العلل
يُحدد C99 أن قيمة FLT_ROUNDS يجب أن تعكس التغييرات في وضع التقريب الحالي، كما يُعيّن بواسطة fesetround(). حالياً، لا يحدث هذا: قيمة FLT_ROUNDS دائماً هي 1.

انظر أيضًا
math_error(7)

ترجمة
تُرجمت هذه الصفحة من الدليل بواسطة زايد السعيدي <zayed.alsaidi@gmail.com>

هذه الترجمة هي وثيقة مجانية؛ راجع رخصة جنو العامة الإصدار 3 (https://www.gnu.org/licenses/gpl-3.0.html) أو ما بعده للاطلاع على شروط حقوق النشر. لا توجد أي ضمانات.

إذا وجدت أي أخطاء في ترجمة صفحة الدليل هذه، يرجى إرسال بريد إلكتروني إلى قائمة بريد المترجمين: kde-l10n-ar@kde.org.