# Implementations

Ready-to-use implementations of the algorithm from [docs/en/03-algorithm.md](https://goudarzjafari.com/persian-calendar/algorithm/) ([فارسی](https://goudarzjafari.com/fa/persian-calendar/algorithm/)) across 14 programming languages.
Every implementation has zero external dependencies, is licensed under MIT, and is thoroughly tested against [`/data`](https://goudarzjafari.com/persian-calendar/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](https://goudarzjafari.com/persian-calendar/implementations/python/#file-persian-calendar-py)                                                                                       | [test](https://goudarzjafari.com/persian-calendar/implementations/python/#file-test-persian-calendar-py)      | `python -m unittest`                                                         | Python 3.13                     |
| JavaScript (ESM)               | [persian-calendar.js](https://goudarzjafari.com/persian-calendar/implementations/javascript/#file-persian-calendar-js)                                                                                   | [test](https://goudarzjafari.com/persian-calendar/implementations/javascript/#file-persian-calendar-test-js)  | `node --test`                                                                | Node.js 26                      |
| TypeScript                     | [persian-calendar.ts](https://goudarzjafari.com/persian-calendar/implementations/typescript/#file-persian-calendar-ts)                                                                                   | [test](https://goudarzjafari.com/persian-calendar/implementations/typescript/#file-persian-calendar-test-ts)  | `node --test` (Node 23.6+)                                                   | Node.js 26, tsc strict          |
| Java 16+                       | [PersianCalendar.java](https://goudarzjafari.com/persian-calendar/implementations/java/#file-persiancalendar-java)                                                                                       | [test](https://goudarzjafari.com/persian-calendar/implementations/java/#file-persiancalendartest-java)        | `javac -d out *.java && java -cp out PersianCalendarTest`                    | Java 26                         |
| Kotlin (JVM/Android, KMP core) | [PersianCalendar.kt](https://goudarzjafari.com/persian-calendar/implementations/kotlin/#file-persiancalendar-kt)                                                                                         | [test](https://goudarzjafari.com/persian-calendar/implementations/kotlin/#file-persiancalendartest-kt)        | `kotlinc *.kt -include-runtime -d t.jar && java -jar t.jar`                  | Kotlin 2.4                      |
| Scala 3                        | [PersianCalendar.scala](https://goudarzjafari.com/persian-calendar/implementations/scala/#file-persiancalendar-scala)                                                                                    | [test](https://goudarzjafari.com/persian-calendar/implementations/scala/#file-persiancalendartest-scala)      | `scala run . --main-class persiancalendar.PersianCalendarTest -- ../../data` | Scala 3.9                       |
| C# (.NET 6+)                   | [SolarHijri.cs](https://goudarzjafari.com/persian-calendar/implementations/csharp/#file-solarhijri-cs)                                                                                                   | [test](https://goudarzjafari.com/persian-calendar/implementations/csharp/#file-tests-program-cs)              | `cd tests && dotnet run`                                                     | .NET 8                          |
| Go 1.21+                       | [persiancalendar.go](https://goudarzjafari.com/persian-calendar/implementations/go/#file-persiancalendar-go)                                                                                             | [test](https://goudarzjafari.com/persian-calendar/implementations/go/#file-persiancalendar-test-go)           | `go test ./...`                                                              | Go 1.27                         |
| Rust 2024 (1.85+)              | [src/lib.rs](https://goudarzjafari.com/persian-calendar/implementations/rust/#file-src-lib-rs)                                                                                                           | [test](https://goudarzjafari.com/persian-calendar/implementations/rust/#file-tests-data-rs)                   | `cargo test --release`                                                       | Rust 1.98                       |
| PHP 8.1+                       | [PersianCalendar.php](https://goudarzjafari.com/persian-calendar/implementations/php/#file-persiancalendar-php)                                                                                          | [test](https://goudarzjafari.com/persian-calendar/implementations/php/#file-test-php)                         | `php test.php`                                                               | PHP 8.5                         |
| Dart 3 / Flutter               | [lib/persian_calendar.dart](https://goudarzjafari.com/persian-calendar/implementations/dart/#file-lib-persian-calendar-dart)                                                                             | [test](https://goudarzjafari.com/persian-calendar/implementations/dart/#file-test-persian-calendar-test-dart) | `dart pub get && dart test`                                                  | Dart 3.13                       |
| C99 / C++                      | [persian_calendar.h](https://goudarzjafari.com/persian-calendar/implementations/c/#file-persian-calendar-h), [.c](https://goudarzjafari.com/persian-calendar/implementations/c/#file-persian-calendar-c) | [test](https://goudarzjafari.com/persian-calendar/implementations/c/#file-test-c)                             | `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](https://goudarzjafari.com/persian-calendar/implementations/ruby/#file-persian-calendar-rb)                                                                                         | [test](https://goudarzjafari.com/persian-calendar/implementations/ruby/#file-test-persian-calendar-rb)        | `ruby test_persian_calendar.rb`                                              | Ruby 4.0                        |
| PostgreSQL                     | [postgresql.sql](https://goudarzjafari.com/persian-calendar/implementations/postgresql/#file-postgresql-sql)                                                                                             | [test](https://goudarzjafari.com/persian-calendar/implementations/postgresql/#file-test-postgresql-mjs)       | `npm install && npm test`                                                    | PostgreSQL 17 (PGlite)          |

## What is verified for each language

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`](https://goudarzjafari.com/persian-calendar/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 `List`s, `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

| 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

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.

---

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