math_error(7)

الاسم
math_error - كشف الأخطاء من الدوال الرياضية

موجز
#include <math.h>
#include <errno.h>
#include <fenv.h>

الوصف
عند حدوث خطأ، تشير معظم دوال المكتبة إلى ذلك بإرجاع قيمة خاصة (مثل -1 أو NULL). نظرًا لأنها تُرجع عادةً رقمًا عائمًا، فإن الدوال الرياضية المُصرَّح عنها في <math.h> تشير إلى الخطأ باستخدام آليات أخرى. هناك آليتان للإبلاغ عن الأخطاء: القديمة تُعيِّن errno؛ والجديدة تستخدم آلية استثناء النقطة العائمة (استخدام feclearexcept(3) و fetestexcept(3)، كما هو موضح أدناه) الموصوفة في fenv(3).

برنامج محمول يحتاج إلى التحقق من خطأ من دالة رياضية يجب أن يُعيِّن errno إلى الصفر، ويُجري الاستدعاء التالي

    feclearexcept(FE_ALL_EXCEPT);

قبل استدعاء دالة رياضية.

عند العودة من الدالة الرياضية، إذا كان errno غير صفري، أو إذا أعاد الاستدعاء التالي (انظر fenv(3)) قيمة غير صفرية

    fetestexcept(FE_INVALID | FE_DIVBYZERO | FE_OVERFLOW |
                 FE_UNDERFLOW);

فقد حدث خطأ في الدالة الرياضية.

شروط الخطأ التي يمكن أن تحدث للدوال الرياضية موصوفة أدناه.

  خطأ النطاق
يحدث خطأ النطاق عندما تُزود دالة رياضية بوسيطة تقع قيمتها خارج النطاق الذي عُرفت الدالة لأجله (مثل إعطاء وسيطة سالبة لـ log(3)). عند حدوث خطأ نطاق، تُرجع الدوال الرياضية عادةً NaN (على الرغم من أن بعض الدوال تُرجع قيمة مختلفة في هذه الحالة)؛ يُعيَّن errno إلى EDOM، ويُثار استثناء "غير صالح" (FE_INVALID) للنقطة العائمة.

  خطأ القطب
يحدث خطأ القطب عندما تكون النتيجة الرياضية لدالة ما لا نهاية تامة (مثل لوغاريتم 0 هو سالب لا نهاية). عند حدوث خطأ قطب، تُرجع الدالة القيمة (الموقعة) HUGE_VAL أو HUGE_VALF أو HUGE_VALL، اعتمادًا على ما إذا كان نوع نتيجة الدالة هو double أو float أو long double. إشارة النتيجة هي تلك الصحيحة رياضيًا للدالة. يُعيَّن errno إلى ERANGE، ويُثار استثناء "قسمة على صفر" (FE_DIVBYZERO) للنقطة العائمة.

  خطأ النطاق
يحدث خطأ النطاق عندما يعني مقدار نتيجة الدالة أنه لا يمكن تمثيله في نوع نتيجة الدالة. تعتمد قيمة إرجاع الدالة على ما إذا كان خطأ النطاق فيضانًا أو تدفقًا سفليًا.

تحدث فيضان نتيجة عائمة إذا كانت النتيجة محدودة، ولكنها كبيرة جدًا بحيث لا يمكن تمثيلها في نوع النتيجة. عند حدوث فيضان، تُرجع الدالة القيمة HUGE_VAL أو HUGE_VALF أو HUGE_VALL، اعتمادًا على ما إذا كان نوع نتيجة الدالة هو double أو float أو long double. يُعيَّن errno إلى ERANGE، ويُثار استثناء "فيضان" (FE_OVERFLOW) للنقطة العائمة.

تحدث تدفق سفلي نتيجة عائمة إذا كانت النتيجة صغيرة جدًا بحيث لا يمكن تمثيلها في نوع النتيجة. إذا حدث تدفق سفلي، تُرجع الدالة الرياضية عادةً 0.0 (يقول C99 إن الدالة يجب أن تُرجع "قيمة مُعرَّفة بالتنفيذ لا يزيد مقدارها عن أصغر رقم موجب معياري في النوع المحدد"). قد يُعيَّن errno إلى ERANGE، وقد يُثار استثناء "تدفق سفلي" (FE_UNDERFLOW) للنقطة العائمة.

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

ملاحظات
المُعرِّف math_errhandling المحدد بواسطة C99 و POSIX.1 غير مدعوم من glibc. من المفترض أن يشير هذا المُعرِّف إلى أي من آليتي الإخطار بالخطأ (errno، الاستثناءات القابلة للاسترجاع عبر fetestexcept(3)) قيد الاستخدام. تتطلب المعايير أن تكون واحدة على الأقل قيد الاستخدام، ولكنها تسمح بتوفر كلتيهما. الوضع الحالي (glibc 2.8) تحت glibc فوضوي. معظم الدوال (وليس كلها) تُثير استثناءات عند الأخطاء. بعضها أيضًا يُعيِّن errno. دوال قليلة تُعيِّن errno، ولكنها لا تُثير استثناء. عدد قليل جدًا من الدوال لا تفعل أيًا منهما. انظر صفحات الدليل الفردية للتفاصيل.

لتجنب تعقيدات استخدام errno و fetestexcept(3) للتحقق من الأخطاء، يُنصح غالبًا بأن يتحقق المرء بدلاً من ذلك من قيم الوسائط السيئة قبل كل استدعاء. على سبيل المثال، يضمن الكود التالي أن وسيطة log(3) ليست NaN وليست صفرًا (خطأ قطب) أو أقل من الصفر (خطأ نطاق):

    double x, r;

    if (isnan(x) || islessequal(x, 0)) {
        /* Deal with NaN / pole error / domain error */
    }

    r = log(x);

لا ينطبق النقاش في هذه الصفحة على الدوال الرياضية المركبة (أي تلك المُصرَّح عنها بواسطة <complex.h>)، والتي لا يُطلب منها عمومًا إرجاع أخطاء بواسطة C99 و POSIX.1.

يتسبب خيار gcc(1) -fno-math-errno في استخدام الملف التنفيذي لتطبيقات بعض الدوال الرياضية الأسرع من التطبيقات القياسية، ولكنها لا تُعيِّن errno عند الخطأ. (خيار gcc(1) -ffast-math يُفعِّل أيضًا -fno-math-errno.) لا يزال من الممكن اختبار الخطأ باستخدام fetestexcept(3).

انظر أيضًا
gcc(1), errno(3), fenv(3), fpclassify(3), INFINITY(3), isgreater(3), matherr(3), nan(3)

info libc

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

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

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