# پیاده‌سازی‌ها

پیاده‌سازی الگوریتم [بخش ۳ راهنما](https://goudarzjafari.com/fa/persian-calendar/algorithm/) برای ۱۴ زبان برنامه‌نویسی؛ همه بدون وابستگی خارجی (Dependency-free)، با مجوز MIT و تست‌شده با داده‌های مرجع [`/data`](https://goudarzjafari.com/fa/persian-calendar/data/).
کافیه فایل زبان مورد نظرتون رو **همراه با فایل تستش** توی پروژهٔ خودتون کپی کنید.

| Language                       | Code                                                                                                                                                                                                           | Test                                                                                                             | Run the test (from that folder)                                              | Tested with                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------- |
| Python 3.8+                    | [persian_calendar.py](https://goudarzjafari.com/fa/persian-calendar/implementations/python/#file-persian-calendar-py)                                                                                          | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/python/#file-test-persian-calendar-py)      | `python -m unittest`                                                         | Python 3.13                     |
| JavaScript (ESM)               | [persian-calendar.js](https://goudarzjafari.com/fa/persian-calendar/implementations/javascript/#file-persian-calendar-js)                                                                                      | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/javascript/#file-persian-calendar-test-js)  | `node --test`                                                                | Node.js 26                      |
| TypeScript                     | [persian-calendar.ts](https://goudarzjafari.com/fa/persian-calendar/implementations/typescript/#file-persian-calendar-ts)                                                                                      | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/java/#file-persiancalendar-java)                                                                                          | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/kotlin/#file-persiancalendar-kt)                                                                                            | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/scala/#file-persiancalendar-scala)                                                                                       | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/csharp/#file-solarhijri-cs)                                                                                                      | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/csharp/#file-tests-program-cs)              | `cd tests && dotnet run`                                                     | .NET 8                          |
| Go 1.21+                       | [persiancalendar.go](https://goudarzjafari.com/fa/persian-calendar/implementations/go/#file-persiancalendar-go)                                                                                                | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/go/#file-persiancalendar-test-go)           | `go test ./...`                                                              | Go 1.27                         |
| Rust 2024 (1.85+)              | [src/lib.rs](https://goudarzjafari.com/fa/persian-calendar/implementations/rust/#file-src-lib-rs)                                                                                                              | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/rust/#file-tests-data-rs)                   | `cargo test --release`                                                       | Rust 1.98                       |
| PHP 8.1+                       | [PersianCalendar.php](https://goudarzjafari.com/fa/persian-calendar/implementations/php/#file-persiancalendar-php)                                                                                             | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/php/#file-test-php)                         | `php test.php`                                                               | PHP 8.5                         |
| Dart 3 / Flutter               | [lib/persian_calendar.dart](https://goudarzjafari.com/fa/persian-calendar/implementations/dart/#file-lib-persian-calendar-dart)                                                                                | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/c/#file-persian-calendar-h), [.c](https://goudarzjafari.com/fa/persian-calendar/implementations/c/#file-persian-calendar-c) | [test](https://goudarzjafari.com/fa/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/fa/persian-calendar/implementations/ruby/#file-persian-calendar-rb)                                                                                            | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/ruby/#file-test-persian-calendar-rb)        | `ruby test_persian_calendar.rb`                                              | Ruby 4.0                        |
| PostgreSQL                     | [postgresql.sql](https://goudarzjafari.com/fa/persian-calendar/implementations/postgresql/#file-postgresql-sql)                                                                                                | [test](https://goudarzjafari.com/fa/persian-calendar/implementations/postgresql/#file-test-postgresql-mjs)       | `npm install && npm test`                                                    | PostgreSQL 17 (PGlite)          |

## چه چیزهایی برای هر زبان تست شده؟

هر پیاده‌سازی فایل تست مخصوص خودش رو داره (با دستور جدول بالا اجرا می‌شه) و **تمام** این موارد رو بررسی می‌کنه:

| # | مورد تست                                                                                                                                                                                                                                                                                                                                                                                                                                                | حجم تست                |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| ۱ | مقایسهٔ تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ با تقویم نجومی (`data/years.csv`) در هر دو جهت                                                                                                                                                                                                                                                                                                                                                                    | ۶۶۵٬۸۳۷ روز، ۱٬۸۲۳ سال |
| ۲ | تشخیص سال کبیسه، تاریخ نوروز و روز هفتهٔ اول سال برای تمام سال‌های ۱۱۷۸ تا ۳۰۰۰                                                                                                                                                                                                                                                                                                                                                                         | ۱٬۸۲۳ سال              |
| ۳ | نمونه‌های تبدیل تاریخ میلادی ↔ شمسی (`data/test-vectors.csv`) در هر دو جهت                                                                                                                                                                                                                                                                                                                                                                              | ۸٬۵۱۰ تاریخ            |
| ۴ | تبدیل دوطرفه و پیوستگی تک‌تک روزهای سال‌های ۱۰۰۰− تا ۱۱۷۷ و ۳۰۰۱ تا ۴۰۰۰ (برای تست مقادیر منفی در محاسبات میانی)                                                                                                                                                                                                                                                                                                                                        | ۱٫۱۶ میلیون روز        |
| ۵ | **تمام سال‌های بازهٔ مجاز (۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰)**: پیوسته بودن سال‌ها، تبدیل دوطرفهٔ روز اول و آخر هر سال، و تطابق دو جمع کنترلی (۴۸٬۴۸۵ سال کبیسه؛ مجموع JDN نوروزها برابر با ۳۸۹٬۵۹۲٬۹۷۸٬۱۸۰) - دقیقا همون عددهایی که ICU 77.1 به بعد، ICU4X و Temporal می‌دن                                                                                                                                                                                         | ۲۰۰٬۰۰۱ سال            |
| ۶ | اعتبارسنجی تاریخ‌ها: قبول کردن ۳۰ اسفند فقط در سال کبیسه، ۳۰ روزه بودن ماه‌های ۷ تا ۱۲، و رد کردن ماه یا روز ۰ و ماه ۱۳                                                                                                                                                                                                                                                                                                                                 | –                      |
| ۷ | کنترل محدوده و نوع ورودی: بررسی دقیق اولین و آخرین روز مجاز؛ رد کردن حتی یک روز خارج از بازه، اعداد خیلی بزرگ (۲⁵³ یا بزرگ‌ترین عدد صحیح هر زبان) و ورودی‌های غیرصحیح (در زبان‌های پویا). در زبان‌هایی که سال/ماه/روز میلادی رو به شکل عدد می‌گیرن (Python، JS/TS، Rust، PHP، C) تاریخ‌های میلادی نامعتبر مثل `2025-02-29` و `1900-02-29` هم رد می‌شن؛ در بقیهٔ زبان‌ها خود تایپ تاریخ پلتفرم (`LocalDate`، `DateOnly`، `Date`) جلوی این خطا رو می‌گیره | –                      |
| ۸ | تاریخ‌های شناخته‌شده (`2025-03-21` = ۱ فروردین ۱۴۰۴، `1979-02-11` = ۲۲ بهمن ۱۳۵۷) و بررسی تایم‌زون در زبان‌هایی که یک لحظهٔ زمانی ورودی می‌گیرن (JS/TS، Go، PHP، PostgreSQL: مثلا لحظهٔ `2025-03-20T21:00Z` به وقت تهران می‌شه ۱ فروردین ۱۴۰۴، ولی به وقت UTC هنوز ۳۰ اسفند ۱۴۰۳ هست)                                                                                                                                                                   | –                      |

علاوه بر این، خروجی هر زبان برای تک‌تک روزهای سال ۱۱۷۸ تا ۳۰۰۰ در هر دو جهت **با یک موتور تقویم مستقل مقایسه می‌شه**
([`tools/icu-cross-check`](https://goudarzjafari.com/fa/persian-calendar/tools/icu-cross-check/)) و خطاهای احتمالی خاص هر زبان هم جداگانه چک می‌شه:

| زبان       | نسخهٔ تست‌شده                           | مقایسه شده با                                                                         | بررسی‌های اختصاصی هر زبان                                                                                   |
| ---------- | --------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Ruby       | 4.0                                     | ICU4C نسخهٔ 76.1 تا 79.1 (`Fiddle`)                                                   | خطای `TypeError` برای `Float` و `String`، جدول‌های فریز شده، ورودی `Bignum`                                 |
| Python     | 3.13                                    | ICU4C نسخهٔ 76.1 تا 79.1 (`ctypes`)، همهٔ سال‌های کل بازه                             | خطای `TypeError` برای ورودی غیرصحیح، رد کردن `bool`                                                         |
| JavaScript | Node.js 23، 24، 26                      | ICU4C (`Intl`) و Temporal؛ Temporal روی همهٔ سال‌های کل بازه                          | جدول‌های تغییرناپذیر (`Object.freeze`)، کش محدود `Intl`، تاریخ‌های قبل از میلاد                             |
| TypeScript | Node.js 26، `tsc --strict`              | ICU4C (`Intl`) و Temporal                                                             | تمام تست‌های JavaScript + بررسی سخت‌گیرانهٔ تایپ‌ها                                                         |
| Java       | 26                                      | ICU4J نسخهٔ 76.1 تا 79.1، همهٔ سال‌های کل بازه                                        | کامپایل با `-Xlint:all -Werror`، لیست‌های تغییرناپذیر، تست `LocalDate.MIN/MAX`                              |
| Kotlin     | 2.4 (JVM)                               | ICU4J نسخهٔ 76.1 تا 79.1                                                              | سازگار با نسخه‌های قدیمی‌تر اندروید (بدون نیاز به API 30)، `-Werror`                                        |
| Scala      | 3.9                                     | ICU4J نسخهٔ 76.1 تا 79.1                                                              | تست `LocalDate.MAX`                                                                                         |
| C#         | ‎.NET 8                                 | ICU4C نسخهٔ 76.1 تا 79.1 (P/Invoke)؛ `PersianCalendar` در ‎.NET (که از ۱۵۳۵ خطا داره) | تبدیل هشدارهای کامپایلر به خطا، لیست‌های فقط‌خواندنی                                                        |
| Go         | 1.27، amd64 **و 386**                   | ICU4C نسخهٔ 76.1 تا 79.1 (`purego`، بدون نیاز به cgo)                                 | تست با `int` سی‌ودوبیتی، تابع `FromTime` برای تاریخ‌های خیلی دور، `go vet`                                  |
| Rust       | 1.98، ویرایش 2024                       | ICU4X 2.4 روی **تک‌تک روزهای کل بازه** (۷۳٬۰۴۸٬۸۵۰ روز)                               | تست تک‌تک روزهای کل بازه، بیلد debug (بررسی سرریز اعداد) و `clippy`                                         |
| PHP        | 8.5                                     | ICU4C 77.1 (`intl`)                                                                   | فعال بودن `strict_types`، تست `DateTime` برای تاریخ‌های خیلی دور و سال‌های منفی                             |
| Dart       | 3.13، VM **و خروجی وب (JS)**            | ICU4C نسخهٔ 76.1 تا 79.1 (`dart:ffi`)                                                 | رفتار اعداد صحیح در خروجی وب، `dart analyze --fatal-infos`                                                  |
| C / C++    | C99 و C++11/17 (Clang/Zig، و GCC در CI) | ICU4C نسخهٔ 76.1 تا 79.1 (`dlopen` / `LoadLibrary`)                                   | `-Wconversion -Werror`، تست با UBSan و ASan، معماری ۳۲ بیتی x86، `INT64_MIN/MAX` و خروجی `NULL`             |
| PostgreSQL | 17 (PGlite)                             | ICU4C (`Intl`) و Temporal روی تک‌تک روزها                                             | امنیت در برابر دستکاری `search_path`، کار با `search_path` خالی (`pg_dump`)، ایندکس‌ها، `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`           |

### راهنمای توابع (API مشترک)

تمام ۱۴ زبان دقیقا همین مجموعه توابع جدول بالا رو (متناسب با قواعد نام‌گذاری همون زبان، مثل `snake_case`، `camelCase` یا `PascalCase`) در اختیارتون می‌ذارن:

- در **PostgreSQL** و **C**، یک پیشوند `persian_` اول نام توابع قرار می‌گیره (مثل `persian_to_date`، `persian_from_date` و `persian_format`).
- در زبان‌هایی که تایپ تاریخ استاندارد دارن، علاوه بر تبدیل عددی، متدهای کمکی مستقیم هم گذاشته شده: `toLocalDate`/`fromLocalDate` در جاوا، کاتلین و اسکالا؛ `ToDateOnly`/`FromDateOnly` در سی‌شارپ؛ `to_date`/`from_date` در روبی؛ `fromDateTime` در دارت و PHP؛ و `fromDate(date, timeZone)` در جاوااسکریپت و تایپ‌اسکریپت.
- شمارهٔ ماه‌ها در **تمام** پیاده‌سازی‌ها از **۱ تا ۱۲** است (`1` = فروردین تا `12` = اسفند) و روز هفته همیشه از **۰ = شنبه تا ۶ = جمعه** برگردونده می‌شه.

## محدودهٔ ورودی و مدیریت خطاها

| 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`) |

| 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`           |

### محدودهٔ ورودی و مدیریت خطاها در فارسی

در تمام زبان‌ها این سه بازه به صورت ثابت (Constant) تعریف شدن:

- **`VERIFIED_MIN_YEAR` تا `VERIFIED_MAX_YEAR` (`1178` تا `3000`):** بازه‌ای که روزبه‌روز با محاسبات نجومی تطبیق داده شده است.
- **`MIN_YEAR` تا `MAX_YEAR` (`-100000` تا `100000`):** بازهٔ سال‌های مجاز ورودی.
- **`MIN_JDN` تا `MAX_JDN` (`-34576287` تا `38472562`):** بازهٔ شمارهٔ روز جولیانی مجاز (از ۱ فروردین ۱۰۰٬۰۰۰− تا ۲۹ اسفند ۱۰۰٬۰۰۰).

توی این بازه، تمام اعداد میانی فرمول‌ها زیر ۳۲ بیت باقی می‌مونن؛ بنابراین چه روی سیستم‌های ۳۲ بیتی (در C، Go و PHP) و چه با اعداد جاوااسکریپت و خروجی وب دارت، محاسبات کاملا دقیق و بدون سرریز انجام می‌شن. برای هر ورودی خارج از این بازه هم به جای سرریز شدن، گیر کردن در حلقه یا برگردوندن تاریخ اشتباه، خطای مشخص و استاندارد همون زبان (مطابق جدول بالا) برگردونده می‌شه:

- تابع `is_valid_date` هیچ‌وقت استثنا (Exception) پرتاب نمی‌کنه و برای ورودی‌های نامعتبر یا خارج از بازه فقط `false` برمی‌گردونه.
- ورودی‌های میلادی هم کامل اعتبارسنجی می‌شن (مثلا `2025-02-30` خطا می‌ده، نه اینکه بی‌سروصدا به `2025-03-02` تبدیل بشه).
- تمام آرایه‌ها و جدول‌های خروجی (مثل نام ماه‌ها و لیست ۷۸ سال اصلاحی) به صورت تغییرناپذیر (Immutable / Frozen) تعریف شدن تا کدهای بیرونی نتونن اشتباهی تغییرشون بدن.

---

نشانی صفحه: https://goudarzjafari.com/fa/persian-calendar/implementations/
مجوز: متن CC BY 4.0، کد MIT، داده CC0 1.0. نسخهٔ 1.0.0 از https://github.com/Goudarz/PersianCalendar
