داده و راستیآزمایی
ارزیابی کتابخانهها
۴ دقیقه مطالعهبهروزرسانی
پوشهٔ 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/ قرار داده شده است.
روش تست و امتیازدهی
پیوند به بخش روش تست و امتیازدهیهر کتابخونه با دو آزمایش محک زده میشه:
- تست روز اول سال (نوروز) برای سالهای ۱۱۰۰ تا ۳۳۰۰: از کتابخونه میخوایم تاریخ میلادیِ
۱ فروردینتمام این سالها رو حساب کنه و تویresults/<library>.txtبنویسه. بعد ابزارtools/calendar-data(score-libraries) این خروجی رو با تقویم نجومی مقایسه میکنه تا بازهٔ پیوستهٔ سالهای درست (حولوحوش سال ۱۴۰۴) و لیست سالهای اشتباه در بازهٔ ۱۳۰۰ تا ۱۶۰۰ مشخص بشه. - تست روزبهروز (۷۳٬۴۱۴ روز): تکتک روزهای بازهٔ ۱ فروردین ۱۳۰۰ تا ۲۹ اسفند ۱۵۰۰ رو در هر دو جهت (میلادی به شمسی و شمسی به میلادی) تبدیل میکنیم و تعداد خطاها رو در
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:)
$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 بهروز بشه.