پرش به محتوای اصلی
فهرست مطالب

داده و راستی‌آزمایی

ارزیابی کتابخانه‌ها

۴ دقیقه مطالعهبه‌روزرسانی

پوشهٔ implementations/ کدهای خود ما رو نگه می‌داره، اما این‌جا کدهای بقیه رو تست می‌کنیم: یعنی همون کتابخونه‌ها و APIهای داخلی‌ای که برنامه‌نویس‌ها همین الان دارن توی پروژه‌هاشون استفاده می‌کنن (jalaali-js، jdatetime، ICU، PersianCalendar در ‎.NET و…). همهٔ این کتابخونه‌ها رو با داده‌های مرجع یکسان محک زدیم و خروجی همین تست‌ها شد مبنای پیشنهادها و هشدارهایی که توی صفحهٔ ۶ مستندات نوشتیم؛ باگ‌های jalaliday، khayyam و parsi-date هم دقیقا همین‌جا پیدا شدن.

چرا بعضی زبان‌ها این‌جا نیستن؟

پیوند به بخش چرا بعضی زبان‌ها این‌جا نیستن؟
Language What we evaluated Notes
JavaScript / TypeScript Intl (ICU), jalaali-js, moment-jalaali, dayjs + jalaliday, date-fns-jalali TypeScript uses the exact same npm packages, so it shares the JS runner
Python jdatetime, persiantools, convertdate, khayyam
Java ICU4J, samanzamani/PersianDate JDK's java.time has no built-in Persian chronology
Kotlin / Android persian-calendar/calendar Android's built-in android.icu is ICU (tested under Java)
C# / .NET System.Globalization.PersianCalendar (.NET 8 and .NET Framework 4.8), DNTPersianUtils.Core, MD.PersianDateTime.Standard
Go go-jalaali, go-persian-calendar (ptime)
Rust ICU4X (icu_calendar)
PHP intl (ICU), morilog/jalali
Dart / Flutter shamsi_date
Ruby parsi-date Note: the old jalaali gem is not published on RubyGems
Scala – No standalone Scala-only library exists; Scala apps use JVM libraries (tested under Java)
C / C++ – The standard C/C++ library is ICU4C, which runs the exact same engine as ICU4J/Intl/PHP intl (and is tested directly in tools/icu-cross-check)
Swift – Apple's Foundation.Calendar(.persian) wraps ICU and requires macOS/iOS
SQL – Databases have no native Persian calendar except SQL Server's FORMAT(…, 'fa-IR'), which calls .NET's PersianCalendar

یک زبان فقط وقتی توی این پوشه اسکریپت داره که کتابخونهٔ خارجیِ مستقل یا API داخلیِ مجزایی برای تست کردن داشته باشه:

  • TypeScript از همون پکیج‌های npm جاوااسکریپت استفاده می‌کنه؛
  • Scala کتابخونهٔ مجزای مخصوص به خودش رو نداره و از همون کتابخونه‌های جاوا (مثل ICU4J) استفاده می‌کنه؛
  • C و C++‎ از کتابخونهٔ استاندارد ICU4C استفاده می‌کنن که موتور محاسباتیش با ICU4J و Intl یکیه (و توی tools/icu-cross-check مستقیما تست شده)؛
  • Swift در فریم‌ورک Foundation در واقع همون موتور ICU رو صدا می‌زنه؛
  • در SQL هم دیتابیس‌ها تقویم شمسی داخلی ندارن (به‌جز FORMAT(…, 'fa-IR') در SQL Server که از همون PersianCalendar دات‌نت استفاده می‌کنه).

در عین حال، برای هر ۱۴ زبان کد کامل، بدون وابستگی و تست‌شده توی پوشهٔ implementations/ قرار داده شده است.

هر کتابخونه با دو آزمایش محک زده می‌شه:

  1. تست روز اول سال (نوروز) برای سال‌های ۱۱۰۰ تا ۳۳۰۰: از کتابخونه می‌خوایم تاریخ میلادیِ ۱ فروردین تمام این سال‌ها رو حساب کنه و توی results/<library>.txt بنویسه. بعد ابزار tools/calendar-data (score-libraries) این خروجی رو با تقویم نجومی مقایسه می‌کنه تا بازهٔ پیوستهٔ سال‌های درست (حول‌وحوش سال ۱۴۰۴) و لیست سال‌های اشتباه در بازهٔ ۱۳۰۰ تا ۱۶۰۰ مشخص بشه.
  2. تست روزبه‌روز (۷۳٬۴۱۴ روز): تک‌تک روزهای بازهٔ ۱ فروردین ۱۳۰۰ تا ۲۹ اسفند ۱۵۰۰ رو در هر دو جهت (میلادی به شمسی و شمسی به میلادی) تبدیل می‌کنیم و تعداد خطاها رو در results/<library>.everyday.json ثبت می‌کنیم. این تست باگ‌هایی رو شکار می‌کنه که در روز اول فروردین خودشون رو نشون نمی‌دن—مثل باگ عجیب پلاگین jalaliday که تمام روزهای ژانویه و فوریهٔ سال‌های کبیسهٔ میلادی رو یک روز اشتباه حساب می‌کنه!
Runner folder Command (run inside that folder) Requirements
javascript/ npm install && node run.mjs Node.js 22+
python/ pip install -r requirements.txt && python run.py Python 3.9+
java/ java -cp icu4j-79.1.jar Icu4j.java (download com.ibm.icu:icu4j from Maven Central); bash run-saman.sh Java 17+, git
kotlin/ bash run.sh (clones and builds persian-calendar/calendar from source) Kotlin, Java, git
dotnet/ dotnet run -c Release .NET 8 SDK
go/ go mod tidy && go run . Go 1.21+
rust/ cargo run --release Rust 1.85+
php/ composer install && php run.php PHP 8.1+ with intl
dart/ dart pub get && dart run Dart 3
ruby/ bundle install && ruby run.rb Ruby 3+

After running any test script, regenerate results/SUMMARY.md with: cd ../calendar-data && cargo run --release -- score-libraries.

(The .NET Framework 4.8 result file was generated on Windows using PowerShell 5.1:)

PowerShell
$p = New-Object System.Globalization.PersianCalendar
1100..3300 | ForEach-Object { try { "{0} {1:yyyy-MM-dd}" -f $_, $p.ToDateTime($_,1,1,0,0,0,0) } catch {} }

اضافه کردن یک کتابخانهٔ جدید

پیوند به بخش اضافه کردن یک کتابخانهٔ جدید

برای اضافه کردن یک کتابخونهٔ جدید به این بنچمارک: کافیه اسکریپتی بنویسید که فایل results/<name>_<version>.txt رو تولید کنه (خط اول # <name> <version> و در هر خط بعدی <year> <YYYY-MM-DD> برای تاریخ میلادی ۱ فروردین اون سال؛ و در صورت تمایل فایل <same_name>.everyday.json شامل تعداد روزهای غلط در تبدیل‌های روزبه‌روز). در نهایت توی پوشهٔ tools/calendar-data دستور cargo run --release -- score-libraries رو اجرا کنید تا جدول results/SUMMARY.md به‌روز بشه.