Skip to main content
Contents

Implementations

Implementations

4 min readUpdated

Ready-to-use implementations of the algorithm from docs/en/03-algorithm.md (فارسی) across 14 programming languages. Every implementation has zero external dependencies, is licensed under MIT, and is thoroughly tested against /data. Simply copy the file for your language along with its test file into your project.

Language Code Test Run the test (from that folder) Tested with
Python 3.8+ persian_calendar.py test python -m unittest Python 3.13
JavaScript (ESM) persian-calendar.js test node --test Node.js 26
TypeScript persian-calendar.ts test node --test (Node 23.6+) Node.js 26, tsc strict
Java 16+ PersianCalendar.java test javac -d out *.java && java -cp out PersianCalendarTest Java 26
Kotlin (JVM/Android, KMP core) PersianCalendar.kt test kotlinc *.kt -include-runtime -d t.jar && java -jar t.jar Kotlin 2.4
Scala 3 PersianCalendar.scala test scala run . --main-class persiancalendar.PersianCalendarTest -- ../../data Scala 3.9
C# (.NET 6+) SolarHijri.cs test cd tests && dotnet run .NET 8
Go 1.21+ persiancalendar.go test go test ./... Go 1.27
Rust 2024 (1.85+) src/lib.rs test cargo test --release Rust 1.98
PHP 8.1+ PersianCalendar.php test php test.php PHP 8.5
Dart 3 / Flutter lib/persian_calendar.dart test dart pub get && dart test Dart 3.13
C99 / C++ persian_calendar.h, .c test cc -std=c99 -O2 persian_calendar.c test.c -o t && ./t Zig 0.16 (Clang), also as C++17
Ruby 3+ persian_calendar.rb test ruby test_persian_calendar.rb Ruby 4.0
PostgreSQL postgresql.sql test npm install && npm test PostgreSQL 17 (PGlite)

Every implementation passes all of the following checks in its own test suite (which you can run with the command in the table above):

# Test Scope
1 Every single day of 1178–3000 AP compared against the astronomical calendar (data/years.csv), in both directions 665,837 days, 1,823 years
2 Leap-year flag, Nowruz date, and Nowruz weekday for every year in 1178–3000 AP 1,823 years
3 Gregorian ↔ Persian boundary test vectors (data/test-vectors.csv), in both directions 8,510 dates
4 Every day of −1000…1177 and 3001…4000 AP round-trips and steps consecutively (exercising negative intermediate values) 1.16 million days
5 Every year across the full accepted range (−100000…100000): years are contiguous, the first and last day of each year round-trip, and two exact checksums match (48,485 leap years; Nowruz JDN sum = 389,592,978,180)—matching ICU 77.1+, ICU4X, and Temporal 200,001 years
6 Date validation: 30 Esfand accepted only in leap years, months 7–12 capped at 30 days, month/day 0 and month 13 rejected –
7 Input bounds & type safety: exact first and last accepted days; rejection of 1 day outside the range, huge values (2⁵³ or MAX_INT), and non-integers (in dynamic languages). Invalid Gregorian dates (2025-02-29, 1900-02-29) are rejected wherever the API accepts raw (gy, gm, gd) numbers (Python, JS/TS, Rust, PHP, C); in the remaining languages, the platform's own date type (LocalDate, DateOnly, Date) enforces Gregorian validity –
8 Well-known historical dates (2025-03-21 = 1 Farvardin 1404, 1979-02-11 = 22 Bahman 1357), plus time-zone tests wherever the API accepts an instant (JS/TS, Go, PHP, PostgreSQL: 2025-03-20T21:00Z is 1 Farvardin 1404 in Tehran, but still 30 Esfand 1403 in UTC) –

On top of that, each language is cross-checked day by day across 1178–3000 AP against an independent calendar engine (tools/icu-cross-check), and tested against language-specific edge cases:

Language Tested with Cross-checked against Language-specific checks
Ruby 4.0 ICU4C 76.1–79.1 (Fiddle) TypeError for Float/String, frozen tables, Bignum inputs
Python 3.13 ICU4C 76.1–79.1 (ctypes), every year of the full range TypeError for non-integers, bool rejected (isinstance(True, int))
JavaScript Node.js 23, 24, 26 ICU4C (Intl), Temporal; Temporal on every year of the full range Object.freeze tables, bounded Intl cache, dates before 1 CE
TypeScript Node.js 26, tsc --strict ICU4C (Intl), Temporal Same tests as JavaScript + strict type checking
Java 26 ICU4J 76.1–79.1, every year of the full range -Xlint:all -Werror, unmodifiable Lists, LocalDate.MIN/MAX
Kotlin 2.4 (JVM) ICU4J 76.1–79.1 Android-compatible (no API 30+ calls), -Werror
Scala 3.9 ICU4J 76.1–79.1 LocalDate.MAX boundary checks
C# .NET 8 ICU4C 76.1–79.1 (P/Invoke); .NET PersianCalendar (diverges from 1535) Warnings as errors, read-only collections
Go 1.27, amd64 and 386 ICU4C 76.1–79.1 (purego, no cgo) 32-bit int build, FromTime for distant timestamps, go vet
Rust 1.98, edition 2024 ICU4X 2.4 on every day of the full range (73,048,850 days) Full 73M-day sweep in unit test, debug build overflow checks, clippy
PHP 8.5 ICU4C 77.1 (intl) strict_types=1, distant DateTime objects, negative years
Dart 3.13, VM and JavaScript ICU4C 76.1–79.1 (dart:ffi) Web (JS) integer semantics, dart analyze --fatal-infos
C / C++ C99 and C++11/17 (Clang/Zig, GCC in CI) ICU4C 76.1–79.1 (dlopen / LoadLibrary) -Wconversion -Werror, UBSan + ASan, 32-bit x86, INT64_MIN/MAX, NULL output pointers
PostgreSQL 17 (PGlite) ICU4C (Intl) and Temporal, every day search_path injection safety, empty search_path (pg_dump), indexes, NULL, ±infinity
Operation Python / Ruby / Rust / C JavaScript / TS / Java / Kotlin / Scala / Dart / PHP C# Go
Leap year check is_leap_year(y) (Ruby: leap_year?) isLeapYear(y) IsLeapYear IsLeapYear
Days in month days_in_month(y, m) daysInMonth(y, m) DaysInMonth DaysInMonth
Date validation is_valid_date(y, m, d) isValidDate(y, m, d) IsValidDate IsValid
Persian → JDN to_jdn(y, m, d) toJdn(y, m, d) ToJdn ToJdn
JDN → Persian from_jdn(jdn) fromJdn(jdn) FromJdn FromJdn
Gregorian conversion to_gregorian / from_gregorian toGregorian / fromGregorian, or native date type* ToDateOnly / FromDateOnly ToTime / FromTime
Day of week day_of_week(y, m, d) → 0 = Saturday … 6 = Friday dayOfWeek DayOfWeek Weekday
Day of year day_of_year(y, m, d) → 1…366 dayOfYear DayOfYear DayOfYear

PostgreSQL uses the same function names with a persian_ prefix (persian_is_leap_year, persian_days_in_month, persian_is_valid, persian_to_jdn, persian_from_jdn, persian_to_date/persian_from_date, persian_day_of_week(date), persian_day_of_year, persian_format); C also prefixes functions with persian_ and includes persian_day_of_week_jdn.

* Native date helpers: Java/Kotlin/Scala provide toLocalDate/fromLocalDate; Dart provides toDateTimeUtc/fromDateTime; Ruby provides to_date/from_date; PHP adds fromDateTime; JS/TS add fromDate(date, timeZone).

In every language, months are 1-based (1 = Farvardin … 12 = Esfand). Invalid dates raise an exception (or return 0 in C, None in Rust, and an error in Go).

Every implementation defines the same range constants:

Constant Value Meaning
VERIFIED_MIN_YEAR … VERIFIED_MAX_YEAR 1178 … 3000 Years verified day by day against the astronomical calendar
MIN_YEAR … MAX_YEAR −100000 … 100000 Accepted Persian year range
MIN_JDN … MAX_JDN −34576287 … 38472562 Accepted JDN range (1 Farvardin −100000 … 29 Esfand 100000)

(Constant names follow each language's naming convention: VerifiedMinYear, verifiedMinYear, PERSIAN_VERIFIED_MIN_YEAR, etc.)

Within the accepted range, every intermediate calculation fits comfortably in a 32-bit signed integer—so results are 100% exact everywhere, including 32-bit builds (C, Go, PHP) and IEEE-754 double-precision numbers (JavaScript, TypeScript, and Dart compiled to JS). Outside that range, functions never overflow, hang, or return bogus dates:

Language Out-of-range input Non-integer input Invalid calendar date
Python ValueError TypeError ValueError
JavaScript / TypeScript RangeError TypeError RangeError
Ruby RangeError TypeError ArgumentError
Java / Kotlin / Scala IllegalArgumentException (compile-time type error) IllegalArgumentException
C# ArgumentOutOfRangeException (compile-time type error) ArgumentException
PHP InvalidArgumentException TypeError (strict_types) InvalidArgumentException
Dart RangeError (compile-time type error) ArgumentError
Rust None (compile-time type error) None
Go error (compile-time type error) error
C Returns 0, output struct untouched (compile-time type error) Returns 0
PostgreSQL SQLSTATE 22008 (type error) SQLSTATE 22008
  • is_valid_date never throws—it simply returns false for out-of-range or invalid inputs.
  • In Rust, Go, and C, is_leap_year returns a plain boolean and is safe for any integer of its parameter type without overflowing; in all other languages, it rejects years outside MIN_YEAR … MAX_YEAR just like the other functions.
  • Gregorian inputs are strictly validated too (passing 2025-02-30 raises an error instead of silently rolling over to 2025-03-02).
  • All exported tables (month names, correction years) are immutable/frozen so callers cannot accidentally mutate them.