# Library evaluation

> Library evaluation · Jalali Calendar for Developers. While implementations/ contains our own reference code, this folder tests third-party libraries and…

## What this folder is for

While [`implementations/`](https://goudarzjafari.com/persian-calendar/implementations/) contains **our own** reference code, this folder tests **third-party libraries and built-in platform APIs** that developers already use in the wild (`jalaali-js`, `jdatetime`, `persiantools`, ICU, .NET's `PersianCalendar`, etc.).
Every library is benchmarked against the exact same astronomical ground truth ([`data/years.csv`](https://goudarzjafari.com/persian-calendar/files/data/years.csv)), and the output drives the recommendations and warnings in
[docs/en/06-languages-and-libraries.md](https://goudarzjafari.com/persian-calendar/languages-and-libraries/) ([فارسی](https://goudarzjafari.com/fa/persian-calendar/languages-and-libraries/)).
This test suite is how we caught the real-world conversion bugs in `jalaliday`, `khayyam`, and `parsi-date`.

Full score table: [`results/SUMMARY.md`](https://goudarzjafari.com/persian-calendar/tools/library-evaluation/results/).

## Why not every language?

A language has a folder here only if it has a **distinct third-party library or built-in calendar engine** that we can run and evaluate:

| 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/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`                                                                                                  |

Remember: **all 14 languages** have a tested, zero-dependency implementation in [`implementations/`](https://goudarzjafari.com/persian-calendar/implementations/).

## Method

1. **Nowruz boundary test (all libraries):** For every Persian year from `1100` to `3300`, we ask the library for the Gregorian date of `1 Farvardin` and write the output to `results/<library>.txt` (`<year> <YYYY-MM-DD>` per line). Then [`tools/calendar-data`](https://goudarzjafari.com/persian-calendar/tools/calendar-data/) (`score-libraries`) computes the longest unbroken range of accurate years around `1404 AP` and lists any wrong years in `1300–1600 AP`.
2. **Every-day conversion test (73,414 days):** We convert every single day from `1 Farvardin 1300` to `29 Esfand 1500` in both directions (Gregorian → Persian and Persian → Gregorian) and record the count of wrong dates in `results/<library>.everyday.json`. This catches mid-year conversion bugs that a Nowruz-only check would miss—most notably the `jalaliday` bug that shifts all of January and February in Gregorian leap years!

All evaluated libraries are pinned to the exact versions listed in the summary table.

## Running

| 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 {} }
```

## Adding a library

To evaluate another library, generate `results/<name>_<version>.txt` starting with a header line `# <name> <version>` followed by one `<year> <YYYY-MM-DD>` line per Persian year (and optionally `<same_name>.everyday.json` containing `days`, `g2pWrong`, and `p2gWrong`), run `cargo run --release -- score-libraries` inside `tools/calendar-data`, and add the library to page 6 of the guide.

---

Page: https://goudarzjafari.com/persian-calendar/tools/library-evaluation/
License: text CC BY 4.0, code MIT, data CC0 1.0. Version 1.0.0 of https://github.com/Goudarz/PersianCalendar
