تحويل الأعداد إلى كلمات

تحويل الأعداد إلى كلمات#

تكتب NumberToWords::convert() العدد الصحيح بالحروف. اللغة الفارسية (fa) هي الافتراضية، وتغطي كل عدد صحيح دون 10²¹.

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

use RtlyKit\Number\NumberToWords;
use function RtlyKit\number_to_words;

echo NumberToWords::convert(0), "\n";        // صفر
echo NumberToWords::convert(21), "\n";       // بیست و یک
echo NumberToWords::convert(115), "\n";      // صد و پانزده
echo NumberToWords::convert(1001), "\n";     // یک هزار و یک
echo NumberToWords::convert(12345), "\n";    // دوازده هزار و سیصد و چهل و پنج
echo NumberToWords::convert(-45), "\n";      // منفی چهل و پنج
echo number_to_words(2000000000), "\n";      // دو میلیارد
echo NumberToWords::convert(1234567), "\n";
// یک میلیون و دویست و سی و چهار هزار و پانصد و شصت و هفت

تُربط الكلمات بـ « و » (أي «و» العطف) بين كل جزء وآخر، وتتبع كلمةُ المرتبة كلَّ مجموعة: «هزار» (10³) و«میلیون» (10⁶) و«میلیارد» (10⁹) و«تریلیون» (10¹²) و«کوادریلیون» (10¹⁵) و«کوینتیلیون» (10¹⁸). والمجموعة التي تساوي 1 تحتفظ بـ «یک» (1000 هي «یک هزار»؛ ولقراءة «هزار» المجردة استخدم fromWords() أدناه). وتُتخطى المجموعات الصفرية.

المدخلات المقبولة#

نوع المعامل هو int|float|string:

• int: يعمل النطاق الكامل في PHP، بما فيه PHP_INT_MAX: «نه کوینتیلیون و دویست و بیست و سه کوادریلیون ...».
• float: يجب أن يكون منتهيًا وصحيحًا (بلا كسر). 3.0 تعطي «سه»؛ و1.5 تُطلق استثناءً بدل أن تُبتر بصمت.
• string: إشارة اختيارية وأرقام من أي مجموعة أرقام. تُزال الفواصل و٬ والمسافات، فيعمل عدد منسوخ من نموذج. ويمكن أن تكون السلاسل أطول من int في PHP، حتى 21 رقمًا بعد حذف الأصفار البادئة.

echo NumberToWords::convert('۱۲۳٬۴۵۶'), "\n";        // صد و بیست و سه هزار و چهارصد و پنجاه و شش
echo NumberToWords::convert('1,000,000'), "\n";      // یک میلیون
echo NumberToWords::convert('+7'), "\n";             // هفت
echo NumberToWords::convert('-0'), "\n";             // صفر
echo NumberToWords::convert('999999999999999999999'), "\n";
// نهصد و نود و نه کوینتیلیون و نهصد و نود و نه کوادریلیون ... و نهصد و نود و نه

الأخطاء#

المدخل غير الصالح يُطلق InvalidNumberException (صنف فرعي من RtlyKitException). اقرأ الرمز الثابت بـ getErrorCode():

try {
    NumberToWords::convert('1000000000000000000000');
} catch (\RtlyKit\Exceptions\InvalidNumberException $e) {
    echo $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
    // Number is too large (limit is 10^21 - 1). [number_too_large]
}

راجع معالجة الأخطاء لمعرفة كيف تلتقط كل استثناءات المكتبة بنوع واحد.

العربية#

مرّر 'ar' وسيطًا ثانيًا للحصول على العربية الفصحى. تُقرأ اللغة المحلية (locale) من أول حرفين دون تمييز بين الأحرف الكبيرة والصغيرة، فتعمل 'ar_SA' و'AR'، وكذلك 'fa_IR' للفارسية.

echo NumberToWords::convert(11, 'ar'), "\n";        // أحد عشر
echo NumberToWords::convert(21, 'ar'), "\n";        // واحد وعشرون
echo NumberToWords::convert(200, 'ar'), "\n";       // مئتان
echo NumberToWords::convert(3000, 'ar'), "\n";      // ثلاثة آلاف
echo NumberToWords::convert(2000000, 'ar'), "\n";   // مليونان
echo NumberToWords::convert(1002003, 'ar'), "\n";   // مليون وألفان وثلاثة
echo NumberToWords::convert(-7, 'ar'), "\n";        // سالب سبعة

تصل العربية إلى كل عدد صحيح دون 10²⁷، وتقبل خيارات لجنس المعدود والحالة الإعرابية والحركات واسم المليار، وتكتب الأعداد الترتيبية من 1 إلى 99. التفاصيل مع أمثلة كثيرة في الأعداد بالحروف العربية.

اللغة غير المدعومة تُثير UnsupportedLocaleException بالرمز unsupported_locale:

try {
    NumberToWords::convert(5, 'en');
} catch (\RtlyKit\Exceptions\UnsupportedLocaleException $e) {
    echo $e->getMessage(), "\n";   // Unsupported locale 'en' (use 'fa' or 'ar').
}

من الكلمات إلى العدد#

الدالة NumberToWords::fromWords() هي عكس التحويل الفارسي للصيغ التي تنتجها convert(). تُرجع int إذا كانت القيمة تتسع في int في PHP، وstring من الأرقام فيما عدا ذلك.

var_dump(NumberToWords::fromWords('بیست و سه'));                 // int(23)
var_dump(NumberToWords::fromWords('منفی چهل و دو'));             // int(-42)
var_dump(NumberToWords::fromWords('هزار و یک'));                 // int(1001)
var_dump(NumberToWords::fromWords('دو میلیون و سیصد هزار و پنج')); // int(2300005)

// ذهاب وإياب عبر النطاق كله:
var_dump(NumberToWords::fromWords(NumberToWords::convert(PHP_INT_MAX)));
// int(9223372036854775807)
var_dump(NumberToWords::fromWords(NumberToWords::convert('999999999999999999999')));
// string(21) "999999999999999999999"

كيف تُقرأ الكلمات#

• يُطبَّع المدخل أولًا: تتحول صور الحروف العربية إلى فارسية («ك» إلى «ک»، و«ي» إلى «ی»)، ويُعامل ZWNJ مسافةً، وتُتجاهل المسافات الزائدة.
• «منفی» في البداية تجعل النتيجة سالبة؛ و«منفی صفر» هي 0.
• كلمة المرتبة دون عدد قبلها تعني واحداً، فـ «هزار» هي 1000.
• يجب أن تكون المراتب تنازلية: «هزار هزار» أو «هزار میلیون» تُطلقان استثناءً.
• لا يجوز أن تتجاوز أي مجموعة 999.
• تُتخطى كلمة «و» أينما ظهرت.

try {
    NumberToWords::fromWords('یکصد');
} catch (\RtlyKit\Exceptions\InvalidNumberException $e) {
    echo $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
    // Unknown number word 'یکصد'. [invalid_number_words]
}

تحمل الأخطاء الرمز invalid_number_words (كلمة غير معروفة، أو تسلسل سيئ التكوين، أو مراتب غير مرتبة، أو نص فارغ) أو input_too_long للنص الذي يتجاوز 4096 بايت.

foreach (['دو صد', 'بیست یک', 'بیست و'] as $text) {
    try {
        NumberToWords::fromWords($text);
    } catch (\RtlyKit\Exceptions\InvalidNumberException $e) {
        echo $e->getMessage(), ' [', $e->getErrorCode()->value, "]\n";
    }
}
// Missing 'و' before 'صد'. [invalid_number_words]
// Missing 'و' before 'یک'. [invalid_number_words]
// Number words cannot end with 'و'. [invalid_number_words]