الأعداد بالحروف العربية

ماذا تفعل#

في العربية يتغير شكل العدد بحسب المعدود. «ثلاثة كتب» و«ثلاث سيارات» تستعملان صيغتين مختلفتين للعدد ثلاثة. ويتغير العدد أيضًا بحسب الحالة الإعرابية، وله قواعده الخاصة في 11 إلى 19 وفي 200 وفي 2000. تتولى NumberToWords::convert($n, 'ar', $options) هذا كله. وبلا خيارات تعطيك صيغة العدّ المجرد، وهي النص نفسه الذي كانت تعطيه الإصدارات السابقة.

الخيارات كائن من RtlyKit\Number\ArabicOptions أو مصفوفة بالمفاتيح نفسها. وتكتب NumberToWords::ordinal() الأعداد الترتيبية من 1 إلى 99. أما الفارسية فلا خيارات لها، وتمرير خيارات مع fa يُثير استثناءً.

البدء السريع#

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

use RtlyKit\Number\ArabicOptions;
use RtlyKit\Number\NumberToWords;

echo NumberToWords::convert(3, 'ar'), "\n";                                       // ثلاثة
echo NumberToWords::convert(1250, 'ar', ['mode' => 'noun', 'gender' => 'f']), "\n";   // ألف ومئتان وخمسون
echo NumberToWords::convert(-5, 'ar', new ArabicOptions(negative: 'ناقص')), "\n";  // ناقص خمسة
echo NumberToWords::ordinal(21), "\n";                                            // الحادي والعشرون
echo NumberToWords::ordinal(21, 'ar', ['gender' => 'f']), "\n";                   // الحادية والعشرون

أي مفتاح أو قيمة أو نوع خاطئ في الخيارات يُثير InvalidNumberException برمز invalid_argument، ولا يظهر TypeError ولا ValueError خام. وتُقرأ اللغة من أول حرفين دون تمييز بين الأحرف الكبيرة والصغيرة، فتعمل 'ar' و'ar_SA' و'AR'.

كل الخيارات#

لكل قيمة ثابت في ArabicOptions أيضًا، مثل ArabicOptions::MODE_NOUN وGENDER_FEMININE وCASE_GENITIVE وDIACRITICS_CASE وHUNDREDS_MA_I_A وBILLION_BILYON. وتبني ArabicOptions::fromArray() الكائن من مصفوفة.

الجنس والمعدود#

اضبط mode على noun حين يأتي بعد العدد معدود، وأعطِ جنس مفرد ذلك المعدود. الأعداد من 3 إلى 10 تخالف المعدود في الجنس، والأعداد من 11 إلى 19 توافقه، والعدد 1 والعدد 2 وآحاد 21 إلى 99 تتبع جنس المعدود أيضًا.

$m = ['mode' => 'noun', 'gender' => 'm'];   // معدود مذكر، مثل «كتاب»
$f = ['mode' => 'noun', 'gender' => 'f'];   // معدود مؤنث، مثل «سيارة»

echo NumberToWords::convert(3, 'ar', $m), "\n";    // ثلاثة
echo NumberToWords::convert(3, 'ar', $f), "\n";    // ثلاث
echo NumberToWords::convert(13, 'ar', $m), "\n";   // ثلاثة عشر
echo NumberToWords::convert(13, 'ar', $f), "\n";   // ثلاث عشرة
echo NumberToWords::convert(11, 'ar', $m), "\n";   // أحد عشر
echo NumberToWords::convert(11, 'ar', $f), "\n";   // إحدى عشرة
echo NumberToWords::convert(21, 'ar', $f), "\n";   // واحدة وعشرون

في الوضع noun تكون آخر كلمة في العدد مضافة إلى المعدود، فيصير 200 «مئتا» و2000 «ألفا» ومليونان «مليونا». أما جنس المعدود الجمع أو اسم الجمع فتحدده أنت، لأن المكتبة لا تخمّنه. وكلمات العدد لا تتضمن المعدود نفسه. والعددان 1 و2 يأتيان في العربية بعد المعدود، فتضعهما أنت في مكانهما.

echo NumberToWords::convert(200, 'ar'), "\n";                          // مئتان
echo NumberToWords::convert(200, 'ar', ['mode' => 'noun']), "\n";      // مئتا
echo NumberToWords::convert(2000, 'ar', ['mode' => 'noun']), "\n";     // ألفا

الحالة الإعرابية#

يغيّر الخيار case حروف الكلمات التي تتغير بالحالة حتى بلا حركات: اثنان واثنين، وعشرون وعشرين، ومئتان ومئتين، وألفان وألفين، واثنا عشر واثني عشر.

echo NumberToWords::convert(2, 'ar', ['case' => 'acc']), "\n";                         // اثنين
echo NumberToWords::convert(20, 'ar', ['case' => 'gen']), "\n";                        // عشرين
echo NumberToWords::convert(200, 'ar', ['case' => 'acc']), "\n";                       // مئتين
echo NumberToWords::convert(2000, 'ar', ['case' => 'acc']), "\n";                      // ألفين
echo NumberToWords::convert(12, 'ar', ['mode' => 'noun']), "\n";                       // اثنا عشر
echo NumberToWords::convert(12, 'ar', ['mode' => 'noun', 'case' => 'gen']), "\n";      // اثني عشر

الحركات#

بالقيمة diacritics: 'case' تكتب المكتبة حركة الإعراب على آخر حرف في كل كلمة لها حركة، ولا تكتب شيئًا غير ذلك: لا حركات داخلية ولا تغيير للهمزات. وتأتي الحركات بالترتيب المعتاد، الحركة قبل الشدة.

echo NumberToWords::convert(125, 'ar', ['diacritics' => 'case']), "\n";
// مئةٌ وخمسةٌ وعشرونَ
echo NumberToWords::convert(125, 'ar', ['diacritics' => 'case', 'case' => 'acc']), "\n";
// مئةً وخمسةً وعشرينَ
echo NumberToWords::convert(125, 'ar', ['diacritics' => 'case', 'case' => 'gen', 'mode' => 'noun']), "\n";
// مئةٍ وخمسةٍ وعشرينَ

الكلمة المضافة إلى معدود أو عدد يليها تأخذ الحركة القصيرة (ضمة أو فتحة أو كسرة)، وغير المضافة تأخذ التنوين. والعشرات تأخذ «ـُونَ» و«ـِينَ». والحركات غير معرَّفة للأعداد الترتيبية، فاستدعاء ordinal() مع diacritics: 'case' يُثير استثناءً.

المئات وطريقة الكتابة#

echo NumberToWords::convert(300, 'ar'), "\n";                                       // ثلاثمئة
echo NumberToWords::convert(300, 'ar', ['hundreds' => 'ma_i_a']), "\n";             // ثلاثمائة
echo NumberToWords::convert(300, 'ar', ['joinHundreds' => false]), "\n";            // ثلاث مئة
echo NumberToWords::convert(800, 'ar', ['joinHundreds' => false]), "\n";            // ثماني مئة
echo NumberToWords::convert(100, 'ar', ['hundreds' => 'ma_i_a']), "\n";             // مائة

«مئة» و«مائة» كلتاهما مستعملة، وكذلك الصيغة الموصولة والمنفصلة. اخترنا الكتابة الأقصر «مئة» والصيغة الموصولة افتراضيًا، وتتيح لك الخيارات الباقي.

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

تستعمل المكتبة النظام القصير. الأسماء هي: ألف، مليون، مليار (أو بليون بالخيار billion: 'bilyon')، تريليون، كوادريليون، كوينتيليون، سكستيليون (10²¹)، سبتيليون (10²⁴). والحد الأعلى كل عدد صحيح دون 10²⁷. ومن 3 إلى 10 من كل مرتبة يُستعمل الجمع (آلاف، ملايين، مليارات، تريليونات ...)، والعدد 2 هو المفرد مع «ان» أو «ين».

echo NumberToWords::convert(5000, 'ar'), "\n";                                // خمسة آلاف
echo NumberToWords::convert(11000, 'ar'), "\n";                               // أحد عشر ألف
echo NumberToWords::convert(1000000000, 'ar'), "\n";                          // مليار
echo NumberToWords::convert(1000000000, 'ar', ['billion' => 'bilyon']), "\n"; // بليون
echo NumberToWords::convert(2000000000, 'ar'), "\n";                          // ملياران
echo NumberToWords::convert('1000000000000', 'ar'), "\n";                     // تريليون
echo NumberToWords::convert('1000000000000000000000000', 'ar'), "\n";         // سبتيليون
echo NumberToWords::convert(102000, 'ar'), "\n";                              // مئة ألف وألفان

يُظهر السطر الأخير خيارًا اخترناه: المجموعة المكونة من مئات مع 1 إلى 10 أمام كلمة المرتبة تُقسم إلى جزأين، كما في «مئة ألف وألفان» للعدد 102 000. فالصيغة الأقصر «مئة وألفان» قد تُفهم أيضًا على أنها 100 + 2000، لذلك نتجنبها. أما المجموعات التي فيها 11 إلى 99 أو لا شيء فتبقى كما هي («مئة وأحد عشر ألف» للعدد 111 000).

العدد 10²⁷ فما فوق يُثير InvalidNumberException برمز number_too_large وسياق limit = 10^27 - 1.

الأعداد السالبة#

يبدأ العدد السالب بكلمة «سالب». غيّر الكلمة بالخيار negative. والصفر لا يكون سالبًا أبدًا.

echo NumberToWords::convert(-5, 'ar'), "\n";                              // سالب خمسة
echo NumberToWords::convert(-5, 'ar', ['negative' => 'ناقص']), "\n";      // ناقص خمسة

الأعداد الترتيبية من 1 إلى 99#

تُرجع NumberToWords::ordinal($n, 'ar', $options) العدد الترتيبي، ولغتها الافتراضية ar. والخيارات المؤثرة هي gender وcase وdefinite. وفي 11 إلى 19 يوافق الجزآن المعدود، ولا حالة إعرابية ظاهرة.

echo NumberToWords::ordinal(1), "\n";                                              // الأول
echo NumberToWords::ordinal(1, 'ar', ['gender' => 'f']), "\n";                     // الأولى
echo NumberToWords::ordinal(3), "\n";                                              // الثالث
echo NumberToWords::ordinal(3, 'ar', ['gender' => 'f']), "\n";                     // الثالثة
echo NumberToWords::ordinal(11), "\n";                                             // الحادي عشر
echo NumberToWords::ordinal(11, 'ar', ['gender' => 'f']), "\n";                    // الحادية عشرة
echo NumberToWords::ordinal(21, 'ar', ['case' => 'gen']), "\n";                    // الحادي والعشرين
echo NumberToWords::ordinal(2, 'ar', ['definite' => false]), "\n";                 // ثان
echo NumberToWords::ordinal(2, 'ar', ['definite' => false, 'case' => 'acc']), "\n"; // ثانيا
echo NumberToWords::ordinal(99), "\n";                                             // التاسع والتسعون

الصفر والأعداد السالبة تُثير invalid_number، وما فوق 99 يُثير number_too_large، واللغة الأخرى تُثير UnsupportedLocaleException. وللأعداد الترتيبية الفارسية استعمل Format::ordinal() من الأرقام وتنسيق الأعداد.

الأخطاء#

try {
    NumberToWords::convert(5, 'ar', ['gender' => 'x']);
} catch (\RtlyKit\Exceptions\InvalidNumberException $e) {
    echo $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
    // Invalid option "gender": expected one of m, f. [invalid_argument]
}

من أين تأتي القواعد#

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

ذو صلة: تحويل الأعداد إلى كلمات للفارسية والاتجاه المعاكس، والحدود.