Data & verification
Library evaluation
2 min readUpdated
What this folder is for
Link to section: What this folder is forWhile 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), and the output drives the recommendations and warnings in
docs/en/06-languages-and-libraries.md (فارسی).
This test suite is how we caught the real-world conversion bugs in jalaliday, khayyam, and parsi-date.
Full score table: results/SUMMARY.md.
Why not every language?
Link to section: 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) |
| 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/.
Method
Link to section: Method- Nowruz boundary test (all libraries): For every Persian year from
1100to3300, we ask the library for the Gregorian date of1 Farvardinand write the output toresults/<library>.txt(<year> <YYYY-MM-DD>per line). Thentools/calendar-data(score-libraries) computes the longest unbroken range of accurate years around1404 APand lists any wrong years in1300–1600 AP. - Every-day conversion test (73,414 days): We convert every single day from
1 Farvardin 1300to29 Esfand 1500in both directions (Gregorian → Persian and Persian → Gregorian) and record the count of wrong dates inresults/<library>.everyday.json. This catches mid-year conversion bugs that a Nowruz-only check would miss—most notably thejalalidaybug 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
Link to section: Running| 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 {} }Adding a library
Link to section: Adding a libraryTo 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.