Skip to main content
Contents

Data & verification

Library evaluation

2 min readUpdated

While 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.

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

  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 (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.

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

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.