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) |
What is verified for each language
Link to section: What is verified for each languageEvery 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 |
Common API
Link to section: Common API| 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).
Input limits and errors
Link to section: Input limits and errorsEvery 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_datenever throws—it simply returnsfalsefor out-of-range or invalid inputs.- In Rust, Go, and C,
is_leap_yearreturns a plain boolean and is safe for any integer of its parameter type without overflowing; in all other languages, it rejects years outsideMIN_YEAR … MAX_YEARjust like the other functions. - Gregorian inputs are strictly validated too (passing
2025-02-30raises an error instead of silently rolling over to2025-03-02). - All exported tables (month names, correction years) are immutable/frozen so callers cannot accidentally mutate them.