phpcommon intmath

phpcommon intmath

أحدث إصدار: 1.0.0 بيتا

مكتبة PHP 5.3+ للعمليات الحسابية على الأعداد الصحيحة التي تلتف عند تجاوز السعة.

انتباه

هذه المكتبة غير مخصصة للاستخدام كوسيلة لإجراء العمليات الحسابية بشكل صحيح على الأعداد الصحيحة ولا ينبغي استخدامها بدلاً من العوامل الحسابية الأصلية أو أي مكتبة أخرى مصممة لهذا الغرض.

على عكس اللغات الأخرى التي تتجاوز الأعداد الصحيحة الموجبة الكبيرة إلى أعداد صحيحة سالبة كبيرة، فإن لغة PHP في الواقع تتجاوز الأعداد الصحيحة إلى أرقام الفاصلة العائمة. في معظم الحالات، يجب التعامل مع التجاوزات الحسابية على أنها ظرف غير عادي يتطلب معالجة خاصة. ومع ذلك، هناك بعض الحالات التي يكون فيها هذا السلوك الالتفافي مفيدًا بالفعل - على سبيل المثال مع أرقام تسلسل TCP أو خوارزميات معينة، مثل حساب التجزئة. توفر فئة الأداة المساعدة هذه وظائف حسابية أساسية تعمل وفقًا لهذا السلوك.

وللتوضيح، خذ المثال التالي:

 // Output on 64-bit system: float(9.2233720368548E+18)
var_dump ( PHP_MAX_INT + 1 );

// Output on 64-bit system: int(-9223372036854775808)
var_dump (IntMath:: add ( PHP_MAX_INT , 1 ));

كما هو موضح سابقًا، فإن إضافة واحد إلى أكبر عدد صحيح مدعوم باستخدام عوامل حسابية أصلية سيؤدي إلى رقم الفاصلة العائمة. على النقيض من ذلك، فإن استخدام IntMath::add() سيؤدي إلى تجاوز السعة، مما يؤدي إلى أصغر عدد صحيح مدعوم في هذا الإصدار من PHP.

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

تثبيت

استخدم Composer لتثبيت الحزمة:

$ composer require phpcommon/intmath

العمليات

حاليًا، يتم دعم العمليات الحسابية الأربع الأساسية فقط (الجمع والطرح والضرب والقسمة) والنفي.

النفي

بالنسبة للقيم الصحيحة، النفي هو نفس الطرح من الصفر. نظرًا لأن PHP تستخدم تمثيل مكملين للأعداد الصحيحة ولأن نطاق قيم مكملتين غير متماثل، فإن إلغاء الحد الأقصى لعدد صحيح سالب يؤدي إلى نفس الحد الأقصى لعدد سالب. على الرغم من حدوث تجاوز السعة، لم يتم طرح أي استثناء.

لجميع القيم الصحيحة $a , -$a يساوي (~$a) + 1 .

استخدام مثال واجهة برمجة التطبيقات:

 // Outputs int(-100)
var_dump (IntMath:: negate ( 100 ));

إضافة

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

استخدام مثال واجهة برمجة التطبيقات:

 // Outputs int(300)
var_dump (IntMath:: add ( 100 , 200 ));

الطرح

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

استخدام مثال واجهة برمجة التطبيقات:

 // Outputs int(90)
IntMath:: subtract ( 100 , 10 );

الضرب

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

استخدام مثال واجهة برمجة التطبيقات:

 // Outputs int(200)
IntMath:: multiply ( 100 , 2 );

قسم

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

هناك حالة خاصة واحدة لا تستوفي هذه القاعدة: إذا كان المقسوم هو عدد صحيح سالب لأكبر حجم ممكن لنوعه، والمقسوم عليه هو -1 ، فسيحدث تجاوز عدد صحيح وتكون النتيجة مساوية للمقسوم. على الرغم من تجاوز السعة، لم يتم طرح أي استثناء في هذه الحالة. من ناحية أخرى، إذا كانت قيمة المقسوم عليه في قسمة عدد صحيح هي 0 ، فسيتم طرح DivisionByZeroException .

استخدام مثال واجهة برمجة التطبيقات:

 // Outputs int(50)
IntMath:: divide ( 100 , 2 );

تغيير السجل

الرجاء مراجعة سجل التغيير لمزيد من المعلومات عما تغير مؤخرًا.

اختبار

$ composer test

تحقق من وثائق الاختبار لمزيد من التفاصيل.

المساهمة

المساهمات في الحزمة هي موضع ترحيب دائما!

• قم بالإبلاغ عن أي أخطاء أو مشكلات تجدها في أداة تعقب المشكلات.
• يمكنك الحصول على الكود المصدري من مستودع Git الخاص بالحزمة.

يرجى الاطلاع على المساهمة والسلوك للحصول على التفاصيل.

حماية

إذا اكتشفت أي مشكلات متعلقة بالأمان، فيرجى إرسال بريد إلكتروني إلى [email protected] بدلاً من استخدام أداة تعقب المشكلات.

الاعتمادات

• ماركوس باسوس

• جميع المساهمين

رخصة

جميع محتويات هذه الحزمة مرخصة بموجب ترخيص MIT.