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

پوشهٔ [`implementations/`](https://goudarzjafari.com/fa/persian-calendar/implementations/) کدهای **خود ما** رو نگه می‌داره، اما این‌جا کدهای **بقیه** رو تست می‌کنیم: یعنی همون کتابخونه‌ها و APIهای داخلی‌ای که برنامه‌نویس‌ها همین الان دارن توی پروژه‌هاشون استفاده می‌کنن (`jalaali-js`، `jdatetime`، ICU، `PersianCalendar` در ‎.NET و…). همهٔ این کتابخونه‌ها رو با داده‌های مرجع یکسان محک زدیم و خروجی همین تست‌ها شد مبنای پیشنهادها و هشدارهایی که توی [صفحهٔ ۶ مستندات](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/) نوشتیم؛ باگ‌های `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`](https://goudarzjafari.com/fa/persian-calendar/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`](https://goudarzjafari.com/fa/persian-calendar/tools/icu-cross-check/) مستقیما تست شده)؛
- **Swift** در فریم‌ورک `Foundation` در واقع همون موتور ICU رو صدا می‌زنه؛
- در **SQL** هم دیتابیس‌ها تقویم شمسی داخلی ندارن (به‌جز `FORMAT(…, 'fa-IR')` در SQL Server که از همون `PersianCalendar` دات‌نت استفاده می‌کنه).

در عین حال، برای **هر ۱۴ زبان** کد کامل، بدون وابستگی و تست‌شده توی پوشهٔ [`implementations/`](https://goudarzjafari.com/fa/persian-calendar/implementations/) قرار داده شده است.

## روش تست و امتیازدهی

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

1. **تست روز اول سال (نوروز) برای سال‌های ۱۱۰۰ تا ۳۳۰۰:** از کتابخونه می‌خوایم تاریخ میلادیِ `۱ فروردین` تمام این سال‌ها رو حساب کنه و توی `results/<library>.txt` بنویسه. بعد ابزار [`tools/calendar-data`](https://goudarzjafari.com/fa/persian-calendar/tools/calendar-data/) (`score-libraries`) این خروجی رو با تقویم نجومی مقایسه می‌کنه تا بازهٔ پیوستهٔ سال‌های درست (حول‌وحوش سال ۱۴۰۴) و لیست سال‌های اشتباه در بازهٔ ۱۳۰۰ تا ۱۶۰۰ مشخص بشه.
2. **تست روزبه‌روز (۷۳٬۴۱۴ روز):** تک‌تک روزهای بازهٔ ۱ فروردین ۱۳۰۰ تا ۲۹ اسفند ۱۵۰۰ رو در هر دو جهت (میلادی به شمسی و شمسی به میلادی) تبدیل می‌کنیم و تعداد خطاها رو در `results/<library>.everyday.json` ثبت می‌کنیم. این تست باگ‌هایی رو شکار می‌کنه که در روز اول فروردین خودشون رو نشون نمی‌دن—مثل باگ عجیب پلاگین `jalaliday` که تمام روزهای ژانویه و فوریهٔ سال‌های کبیسهٔ میلادی رو یک روز اشتباه حساب می‌کنه!

## نحوهٔ اجرا

| Runner folder                                                                                             | Command (run inside that folder)                                                                            | Requirements         |
| --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------- |
| [`javascript/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/javascript) | `npm install && node run.mjs`                                                                               | Node.js 22+          |
| [`python/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/python)         | `pip install -r requirements.txt && python run.py`                                                          | Python 3.9+          |
| [`java/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/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/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/kotlin)         | `bash run.sh` (clones and builds `persian-calendar/calendar` from source)                                   | Kotlin, Java, git    |
| [`dotnet/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/dotnet)         | `dotnet run -c Release`                                                                                     | .NET 8 SDK           |
| [`go/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/go)                 | `go mod tidy && go run .`                                                                                   | Go 1.21+             |
| [`rust/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/rust)             | `cargo run --release`                                                                                       | Rust 1.85+           |
| [`php/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/php)               | `composer install && php run.php`                                                                           | PHP 8.1+ with `intl` |
| [`dart/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/dart)             | `dart pub get && dart run`                                                                                  | Dart 3               |
| [`ruby/`](https://github.com/Goudarz/PersianCalendar/tree/main/tools/library-evaluation/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` به‌روز بشه.

---

نشانی صفحه: https://goudarzjafari.com/fa/persian-calendar/tools/library-evaluation/
مجوز: متن CC BY 4.0، کد MIT، داده CC0 1.0. نسخهٔ 1.0.0 از https://github.com/Goudarz/PersianCalendar
