الأرقام وتنسيق الأعداد

الأرقام#

يحوّل الصنف RtlyKit\Number\Digits بين مجموعات الأرقام الثلاث المستخدمة في البرمجيات الإيرانية: الإنجليزية (0-9) والفارسية (۰-۹، من U+06F0 إلى U+06F9) والعربية الهندية (٠-٩، من U+0660 إلى U+0669). الصنف مجرد استبدال في السلاسل: لا يُطلق استثناءً أبداً، ولا يمسّ المحارف الأخرى، ولا يغيّر الفاصلة العشرية ولا فواصل الآلاف.

<?php
require 'vendor/autoload.php';

use RtlyKit\Number\Digits;

echo Digits::toPersian('Tel 0912 / 2024'), "\n";   // Tel ۰۹۱۲ / ۲۰۲۴
echo Digits::toPersian(1234.5), "\n";              // ۱۲۳۴.۵
echo Digits::toArabic(2026), "\n";                 // ٢٠٢٦
echo Digits::toEnglish('۱۲۳ ٤٥٦ abc'), "\n";        // 123 456 abc
echo Digits::arabicToPersian('٠١٢ 345'), "\n";      // ۰۱۲ 345

convert()#

تطبّع convert() إلى الإنجليزية أولًا ثم تعرض المجموعة المطلوبة. اسم الهدف لا يميّز بين الأحرف الكبيرة والصغيرة: persian وfa وfarsi تعطي أرقامًا فارسية؛ وarabic وar تعطي أرقامًا عربية هندية؛ وأي شيء آخر، بما فيه الخطأ الإملائي، يعطي الإنجليزية.

echo Digits::convert('۱۲۳', 'ar'), "\n";        // ١٢٣
echo Digits::convert('123', 'fa'), "\n";        // ۱۲۳
echo Digits::convert('٣٤٥', 'FARSI'), "\n";     // ۳۴۵
echo Digits::convert('۱۲۳', 'x'), "\n";         // 123

تستخدم أدوات التحقق Digits::toEnglish() في التطبيع، فيمكن للمستخدمين الكتابة بأي مجموعة أرقام؛ راجع التطبيع.

تنسيق الأعداد#

تنسّق Format::withSeparator() العدد بفواصل الآلاف والأرقام الفارسية. تستخدم افتراضيًا فاصل الآلاف العربي ٬ (U+066C) والفاصلة العشرية ٫ (U+066B)، وهما المحرفان اللذان تقضي بهما الطباعة الفارسية. ولا تقرّب أبدًا.

use RtlyKit\Number\Format;

echo Format::withSeparator(1234567), "\n";            // ۱٬۲۳۴٬۵۶۷
echo Format::withSeparator('1,234,567.5'), "\n";      // ۱٬۲۳۴٬۵۶۷٫۵
echo Format::withSeparator('۱٬۲۳۴٫۵'), "\n";          // ۱٬۲۳۴٫۵
echo Format::withSeparator('0001234'), "\n";          // ۱٬۲۳۴
echo Format::withSeparator('+12345'), "\n";           // ۱۲٬۳۴۵
echo Format::withSeparator(1.0), "\n";                // ۱

ما تقبله#

• عدد int، أو float منتهٍ، أو سلسلة رقمية بإشارة اختيارية وأرقام من أي مجموعة من المجموعات الثلاث وكسر اختياري.
• في السلاسل النصية، تُهمل هذه المحارف بوصفها علامات تجميع: , و٬ (U+066C) والمسافات العادية والمسافة غير القابلة للكسر. وتُقرأ الفاصلة العشرية العربية ٫ (U+066B) نقطةً عشرية. والنقطة . العادية نقطة عشرية أيضًا.
• تُحذف الأصفار البادئة من الجزء الصحيح، وتُحذف + البادئة، وتبقى - البادئة.

أي شيء ليس عددًا عشريًا عاديًا بعد هذا التنظيف يُطلق InvalidNumberException: 'abc' والسلسلة الفارغة والتدوين العلمي في السلسلة ('1e5') وNaN أو INF. يحمل الاستثناء رمز خطأ ثابتًا (invalid_number أو non_finite_number أو input_too_long) يمكنك قراءته بـ getErrorCode()؛ راجع معالجة الأخطاء.

فواصل مخصصة#

يستبدل الوسيطان الثاني والثالث فاصلَي الآلاف والكسر العشري. وتظل الأرقام تتحول إلى فارسية:

echo Format::withSeparator(1234567, ','), "\n";            // ۱,۲۳۴,۵۶۷
echo Format::withSeparator(1234567.5, ',', '.'), "\n";     // ۱,۲۳۴,۵۶۷.۵

للحصول على أرقام إنجليزية، حوّل النتيجة بـ Digits::toEnglish().

الأعداد العشرية والدقة#

يُكتب float بأقصر نص عشري يعيد القراءة إلى القيمة نفسها بشرط ألا يتجاوز 15 رقمًا معنوياً، ولا يظهر أبدًا بصيغة أسّية ولا يتأثر بإعدادات php.ini. يُطبع الصفر السالب ۰. يزيل حدّ 15 رقمًا ضجيج التمثيل الثنائي، فتُطبع 0.1 + 0.2 على صورة ۰٫۳. ولا يحمل float أكثر من نحو 15 إلى 17 رقمًا معنوياً، لذلك مرّر سلسلة نصية عندما تحتاج أرقامًا أكثر لأن النص يبقى دقيقًا:

echo Format::withSeparator(0.1 + 0.2), "\n";       // ۰٫۳
echo Format::withSeparator(-1234567.891), "\n";    // -۱٬۲۳۴٬۵۶۷٫۸۹۱
echo Format::withSeparator(1 / 3), "\n";           // ۰٫۳۳۳۳۳۳۳۳۳۳۳۳۳۳۳ (15 رقماً)
echo Format::withSeparator(123456789.123456789), "\n";     // ۱۲۳٬۴۵۶٬۷۸۹٫۱۲۳۴۵۷ (float)
echo Format::withSeparator('123456789.123456789'), "\n";   // ۱۲۳٬۴۵۶٬۷۸۹٫۱۲۳۴۵۶۷۸۹ (نص، دقيق)

حدود الحجم#

try {
    Format::withSeparator(str_repeat('9', 1001));
} catch (\RtlyKit\Exceptions\InvalidNumberException $e) {
    echo $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
    // Number exceeds the 1000 character limit. [input_too_long]
}

يُنسَّق عدد من 1000 رقم بالضبط تنسيقًا عاديًا. وكل الحدود في جدول واحد موجودة في الحدود. تستدعي الدالة المساعدة format_number() الدالة Format::withSeparator() بالقيم الافتراضية.

الأعداد الترتيبية#

تُرجع Format::ordinal() الكلمة الترتيبية الفارسية لعدد صحيح غير سالب. تبني الكلمات الأصلية (الأعداد الأصلية) بـ NumberToWords (راجع تحويل الأعداد إلى كلمات) ثم تطبّق قواعد اللاحقة:

• العدد 1 شاذّ وهو «اول».
• العدد الأصلي المنتهي بـ «سه» يصبح «سوم»؛ وهذا يشمل 23 و33 وهكذا.
• العدد الأصلي المنتهي بـ «ی» (كما في «سی») يأخذ نصف مسافة و«ام».
• وكل ما عدا ذلك يضاف إليه «م» فقط.

echo Format::ordinal(1), "\n";     // اول
echo Format::ordinal(2), "\n";     // دوم
echo Format::ordinal(3), "\n";     // سوم
echo Format::ordinal(21), "\n";    // بیست و یکم
echo Format::ordinal(23), "\n";    // بیست و سوم
echo Format::ordinal(30), "\n";    // سی‌ام
echo Format::ordinal(33), "\n";    // سی و سوم
echo Format::ordinal(100), "\n";   // صدم
echo Format::ordinal(1000), "\n";  // یک هزارم
echo Format::ordinal(0), "\n";     // صفرم
echo Format::ordinal(3.0), "\n";   // سوم

تُقبل الأعداد العشرية الصحيحة مثل 3.0. أما الأعداد السالبة والكسور (2.5) والأعداد العشرية غير المنتهية فتُطلق InvalidNumberException (invalid_number، أو non_finite_number للقيمتين INF وNaN). والدالة المساعدة هي ordinal().