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

كتابة الأعداد الصحيحة بالحروف بالفارسية (حتى 10^21) وبالعربية (حتى 10^27)، وقراءة كلمات الأعداد الفارسية وتحويلها إلى أعداد عبر fromWords().

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

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

PHP

<?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";
// یک میلیون و دویست و سی و چهار هزار و پانصد و شصت و هفت

تُربط الكلمات بـ « و » (أي «و» العطف) بين كل جزء وآخر، وتتبع كلمةُ المرتبة كلَّ مجموعة: «هزار» (103) و«میلیون» (106) و«میلیارد» (109) و«تریلیون» (1012) و«کوادریلیون» (1015) و«کوینتیلیون» (1018). والمجموعة التي تساوي 1 تحتفظ بـ «یک» (1000 هي «یک هزار»؛ ولقراءة «هزار» المجردة استخدم fromWords() أدناه). وتُتخطى المجموعات الصفرية.

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

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

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

PHP

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():

المدخل	رمز الخطأ
`1.5`، `'12a'`، `''`	`invalid_number`
`NAN`، `INF`	`non_finite_number`
سلسلة أطول من 4096 بايت	`input_too_long`
`1e21`، `'1000000000000000000000'` (22 رقمًا)	`number_too_large`

PHP

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' للفارسية.

PHP

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";        // سالب سبعة

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

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

PHP

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 من الأرقام فيما عدا ذلك.

PHP

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.
تُتخطى كلمة «و» أينما ظهرت.

PHP

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 بايت.

من المفيد أن تعرف. fromWords() دقيقة في القراءة: ترفض «و» الناقصة بين الأجزاء («دو صد» و«بیست یک»)، و«و» في آخر العبارة، والأجزاء غير المرتبة (مئات ثم عشرات ثم آحاد)، وتُثير invalid_number_words. وكل نص تنتجه convert() تقرؤه. وهي تقرأ الفارسية فقط: الكلمات العربية الناتجة عن convert($n, 'ar') والأعداد الترتيبية مثل «سی‌ام» والصيغة المختصرة «یکصد» تُثير استثناءً.

PHP

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]