سقف‌ها

این سقف‌ها عمدی هستند. هر فراخوانی را ارزان و قابل‌پیش‌بینی نگه می‌دارند و نمی‌گذارند ورودی نامطمئن به تاریخ سرریزشده یا محاسبهٔ سنگین تبدیل شود. از هر سقف که رد شوید، یک RtlyKitException مستند می‌گیرید (مدیریت خطا). در اعتبارسنج‌ها یک Result نامعتبر می‌گیرید.

بازهٔ سال تقویم‌ها

هر تاریخ پشتیبانی‌شده در هر تقویم به یک سال میلادی بین ۱ و ۹۹۹۹ می‌رسد. پس هر مقداری که کلاس‌ها بسازند در یک DateTimeImmutable جا می‌شود و سرریز نمی‌کند. بازه‌ها همان ثابت‌های عمومی MIN_YEAR و MAX_YEAR هستند:

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

use RtlyKit\Calendar\{Hebrew, Hijri, Jalali};

foreach ([Jalali::class, Hijri::class, Hebrew::class] as $class) {
    printf(
        "%-7s %5d..%-5d  %s .. %s\n",
        (new ReflectionClass($class))->getShortName(),
        $class::MIN_YEAR,
        $class::MAX_YEAR,
        $class::create($class::MIN_YEAR, 1, 1)->toGregorian()->format('Y-m-d'),
        $class::create($class::MAX_YEAR, 1, 1)->toGregorian()->format('Y-m-d'),
    );
}
// Jalali   -620..9377   0001-03-21 .. 9998-03-20
// Hijri       1..9665   0622-07-19 .. 9998-10-12
// Hebrew   3762..13759  0001-09-06 .. 9998-10-15

همهٔ راه‌های ورود از این بازه پیروی می‌کنند: make، create، createFromFormat، زمان یونیکس، add*() و sub*() (حتی با مقدار خیلی بزرگ)، توابع کمکی و ماکروهای Carbon. مقدار بیرون از بازه InvalidDateException می‌دهد. هیچ چیز تاریخ سرریزشده نمی‌دهد و TypeError یا ValueError بیرون نمی‌آید.

مقدار افزودن و زمان یونیکس

• مقدار addDays() و subDays() (و ساعت، دقیقه، ثانیه) اگر از کل بازهٔ تقویم بزرگ‌تر باشد (حدود ۳٫۷ میلیون روز، یا همین بازه برحسب ساعت و دقیقه و ثانیه) از همان اول با InvalidDateException رد می‌شود. مقدار کوچک‌تری که تاریخ را از سال‌های پشتیبانی‌شده بیرون ببرد هم رد می‌شود.
• زمان یونیکس باید در سال‌های میلادی ۱ تا ۹۹۹۹ باشد (با کمی جا برای منطقهٔ زمانی). دورتر از آن رد می‌شود.
• Hebrew::addMonths() و addYears() هر قدر مقدار بزرگ باشد، زمان یکسانی می‌برند.

آستانهٔ سال در رشته

رشته‌ای مثل 1405/01/01 یا 1405-01-01 که به make() یا یک تابع کمکی بدهید، اگر سالش از آستانه کمتر باشد تاریخ خود همان تقویم خوانده می‌شود. وگرنه رشتهٔ میلادی است:

برای دادن تاریخ میلادی واقعی زیر آستانه (مثلاً سال ۹۹۹) از DateTimeImmutable استفاده کنید. آن هیچ‌وقت دوباره تفسیر نمی‌شود. پرسش‌های متداول را ببینید.

بازهٔ ام‌القری

• جدول ماه‌های ام‌القری داخل بسته سال‌های ۱۳۰۰ تا ۱۵۰۰ هجری قمری را پوشش می‌دهد (از 1882-11-12 تا 2077-11-16). بیرون از آن، و برای HijriVariant::Tabular همیشه، Hijri قاعدهٔ حسابی به کار می‌برد که ممکن است یکی دو روز با رؤیت فرق کند. Hijri::hasUmmAlQuraData($year) می‌گوید یک سال پوشش دارد یا نه. سال‌های ۱۳۱۸ تا ۱۵۰۰ با تقویم رسمی KACST مقایسه شده‌اند ( Hijri::ummAlQuraVerifiedRange() ).
• IranHolidays برای سال‌های جلالی ۱۳۸۰ تا ۱۴۰۵ تاریخ‌های رسمی یا گزارش‌شده را به کار می‌برد. برای بقیهٔ سال‌ها، تعطیلات اسلامی را فقط داخل بازهٔ ام‌القری می‌دهد. بیرون از آن و برای سال‌های قبل از مبدأ هجری فقط تعطیلات ثابت جلالی می‌آید، بدون خطا. all() و allTitles() و allFixed() برای هر سال جلالی از ‎-620 تا 9377 کار می‌کنند.

سقف اندازهٔ ورودی

این سقف‌ها جزو تعهد کتابخانه‌اند (پایداری API).

بازهٔ عددها

use function RtlyKit\number_to_words;

echo number_to_words(999999999, 'ar'), "\n";
// تسعمئة وتسعة وتسعون مليون وتسعمئة وتسعة وتسعون ألف وتسعمئة وتسعة وتسعون
// number_to_words(str_repeat('9', 27), 'ar') خطای InvalidNumberException می‌دهد (number_too_large، limit برابر "10^27 - 1")
// number_to_words(str_repeat('9', 22)) خطای InvalidNumberException می‌دهد (number_too_large، limit برابر "10^21 - 1")

بازهٔ تنظیم‌ها

پوشش داده

این جدول‌ها بر چه پایه‌ای هستند: دقت و داده.

پلتفرم

PHP نسخهٔ ۸٫۲ تا ۸٫۵ بدون هیچ افزونهٔ اضافه، Laravel 11 و 12 و 13، و Carbon 3. پایداری API را ببینید.