پیادهسازیها
پیادهسازیها
۶ دقیقه مطالعهبهروزرسانی
پیادهسازی الگوریتم بخش ۳ راهنما برای ۱۴ زبان برنامهنویسی؛ همه بدون وابستگی خارجی (Dependency-free)، با مجوز MIT و تستشده با دادههای مرجع /data.
کافیه فایل زبان مورد نظرتون رو همراه با فایل تستش توی پروژهٔ خودتون کپی کنید.
| 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) |
چه چیزهایی برای هر زبان تست شده؟
پیوند به بخش چه چیزهایی برای هر زبان تست شده؟هر پیادهسازی فایل تست مخصوص خودش رو داره (با دستور جدول بالا اجرا میشه) و تمام این موارد رو بررسی میکنه:
| # | مورد تست | حجم تست |
|---|---|---|
| ۱ | مقایسهٔ تکتک روزهای سال ۱۱۷۸ تا ۳۰۰۰ با تقویم نجومی (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) و خطاهای احتمالی خاص هر زبان هم جداگانه چک میشه:
| زبان | نسخهٔ تستشده | مقایسه شده با | بررسیهای اختصاصی هر زبان |
|---|---|---|---|
| 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 مشترک)
پیوند به بخش راهنمای توابع (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) تعریف شدن تا کدهای بیرونی نتونن اشتباهی تغییرشون بدن.