پرش به محتوای اصلی
فهرست مطالب

فصل ۳ از ۱۰

الگوریتم

۱۰ دقیقه مطالعهبه‌روزرسانی

این صفحه مشخصات کامل الگوریتمی رو توضیح می‌ده که توی تمام پیاده‌سازی‌های این مخزن استفاده شده است. این الگوریتم فقط با اعداد صحیح (Integer) کار می‌کنه، به جز لیست ۷۸ سال استثنا به هیچ جدول دیگه‌ای نیاز نداره و کل کدش توی هر زبانی حدود ۶۰ خط می‌شه.

اگر برای زبان برنامه‌نویسی شما کتابخونهٔ استاندارد و خوبی وجود داره (بخش ۶: زبان‌ها و کتابخانه‌ها)، پیشنهاد می‌کنیم از همون استفاده کنید. سراغ پیاده‌سازی دستی این الگوریتم زمانی برید که کتابخونهٔ مناسبی برای زبانتون نیست، نمی‌خواید وابستگی (Dependency) به پروژه اضافه کنید، یا توی محیط‌هایی مثل SQL، سیستم‌های Embedded یا اکسل کار می‌کنید.

ایدهٔ اصلی: تبدیل از طریق شمارندهٔ روز

پیوند به بخش ایدهٔ اصلی: تبدیل از طریق شمارندهٔ روز

هیچ‌وقت سعی نکنید تاریخ شمسی رو مستقیم به میلادی تبدیل کنید. راه‌حل درست و تمیز اینه که هر دو تقویم رو به یک شمارهٔ روز مشترک تبدیل کنید:

Persian date  ──to_jdn──▶  JDN  ──jdn_to_gregorian──▶  Gregorian date
Persian date  ◀─from_jdn──  JDN  ◀─gregorian_to_jdn──  Gregorian date

عدد روز ژولینی (JDN یا Julian Day Number) یک شمارندهٔ استاندارد روز در علم نجومه (روز صفر در این شمارش برابر با ۱ ژانویهٔ ۴۷۱۳ قبل از میلاد در تقویم ژولینی هست). البته از هر شمارندهٔ روز دیگه‌ای هم می‌تونید استفاده کنید؛ فقط مهم اینه که در هر دو طرف تبدیل، مبنای شمارش یکسان باشه:

شمارندهٔ روز رابطهٔ تبدیل به JDN
روزهای یونیکس (LocalDate.toEpochDay()، تعداد روزهای گذشته از 1970-01-01) unix_days + 2440588
DateOnly.DayNumber در ‎.NET (تعداد روزهای گذشته از 0001-01-01) day_number + 1721426
Rata Die (شمارندهٔ کتاب Calendrical Calculations) rd + 1721425
نوع دادهٔ date در PostgreSQL (d - DATE '2000-01-01') + 2451545
Date#jd در روبی، یا gregoriantojd() در PHP خودشون مستقیما JDN هستن

وقتی تاریخ رو به شمارهٔ روز تبدیل کنید، پیدا کردن روز هفته، حساب کردن فاصلهٔ بین دو تاریخ و «اضافه کردن N روز به تاریخ» هم به یک جمع و تفریق ساده تبدیل می‌شن.

تقسیم صحیح (Floor Division): تنها تلهٔ ماجرا

پیوند به بخش تقسیم صحیح (Floor Division): تنها تلهٔ ماجرا

فرمول‌های تقویم به تقسیم صحیح کف (Floor division) و باقی‌ماندهٔ کف (Floor modulo) نیاز دارن؛ یعنی خارج‌قسمت باید همیشه به سمت منفی بی‌نهایت گرد بشه. توی خیلی از زبان‌های برنامه‌نویسی، عملگرهای / و % روی اعداد صحیح به سمت صفر گرد می‌کنن (Truncating division). برای اعداد مثبت هر دو روش یک جواب می‌دن، اما برای اعداد منفی خروجی‌شون فرق می‌کنه! از اونجایی که بعضی از مقادیر میانی یا سال‌های قبل از مبدأ ممکنه منفی بشن، حتما باید از عملگر یا تابع کمکی درست استفاده کنید:

زبان تقسیم کف ⌊a / b⌋ باقی‌ماندهٔ کف
Python، Ruby a // b (در پایتون)، a / b (در روبی) a % b
JavaScript / TypeScript Math.floor(a / b) a - b * Math.floor(a / b)
Java Math.floorDiv(a, b) Math.floorMod(a, b)
Kotlin a.floorDiv(b) a.mod(b)
Rust a.div_euclid(b) (برای b > 0 یکسانه) a.rem_euclid(b)
C، C++‎، C#‎، Go، PHP، Swift، SQL نوشتن تابع کمکی (q = a / b; if (a % b != 0 && (a < 0) != (b < 0)) q--;) a - b * floor_div(a, b)
Dart (a - a % b) ~/ b (چون % در دارت برای b > 0 همیشه نامنفیه) a % b

اعداد صحیح ۳۲ بیتی برای کل بازهٔ سال‌های ۱ تا ۹۹۹۹ میلادی کاملا کافی هستن (چون بزرگ‌ترین عدد میانی فرمول یعنی 33 × (jdn − EPOCH) از ۲³¹ کوچکتر می‌مونه). با این حال، اگر توابعتون ورودی‌های دلخواه و کنترل‌نشده از بیرون می‌گیرن، بهتره از اعداد ۶۴ بیتی استفاده کنید یا اول محدودهٔ ورودی رو چک کنید.

EPOCH = 1948320        # JDN of 1 Farvardin 1 as the formula computes it (a calibration constant;
                       # the astronomical Nowruz of year 1 was JDN 1948321, one day later)
CORRECTIONS = {1502, 1601, 1634, …, 2987}   # the 78 years from data/corrections.txt
function is_leap_year(y):
    if y in CORRECTIONS:       return false
    if y - 1 in CORRECTIONS:   return true
    return floor_mod(25*y + 11, 33) < 8

2. Days in month, validity · طول ماه و اعتبار تاریخ

پیوند به بخش 2. Days in month, validity · طول ماه و اعتبار تاریخ
function days_in_month(y, m):          # m = 1..12
    if m <= 6:  return 31
    if m <= 11: return 30
    return is_leap_year(y) ? 30 : 29

function is_valid(y, m, d):
    return 1 <= m <= 12 and 1 <= d <= days_in_month(y, m)

3. Persian → JDN · شمسی به شمارهٔ روز

پیوند به بخش 3. Persian → JDN · شمسی به شمارهٔ روز
function nowruz_jdn(y):                # JDN of 1 Farvardin of year y
    jdn = EPOCH + 365*(y - 1) + floor_div(8*y + 21, 33)
    if y - 1 in CORRECTIONS: jdn = jdn - 1
    return jdn

function days_before_month(m):         # days in months 1..m-1
    return m <= 7 ? 31*(m - 1) : 30*(m - 1) + 6

function to_jdn(y, m, d):
    require is_valid(y, m, d)
    return nowruz_jdn(y) + days_before_month(m) + d - 1

4. JDN → Persian · شمارهٔ روز به شمسی

پیوند به بخش 4. JDN → Persian · شمارهٔ روز به شمسی
function from_jdn(jdn):
    y = 1 + floor_div(33*(jdn - EPOCH) + 3, 12053)    # estimate (12053 = days in 33 years)
    while jdn >= nowruz_jdn(y + 1): y = y + 1
    while jdn <  nowruz_jdn(y):     y = y - 1
    doy = jdn - nowruz_jdn(y)                          # 0-based day of year
    if doy < 186:                                      # months 1-6 have 31 days
        return (y, floor_div(doy, 31) + 1, doy mod 31 + 1)
    doy = doy - 186                                    # months 7-12 have 30 days
    return (y, floor_div(doy, 30) + 7, doy mod 30 + 1)

5. Gregorian ↔ JDN · میلادی و شمارهٔ روز

پیوند به بخش 5. Gregorian ↔ JDN · میلادی و شمارهٔ روز
function gregorian_to_jdn(y, m, d):
    a = floor_div(14 - m, 12)
    yy = y + 4800 - a
    mm = m + 12*a - 3
    return d + floor_div(153*mm + 2, 5) + 365*yy + floor_div(yy, 4)
             - floor_div(yy, 100) + floor_div(yy, 400) - 32045

function jdn_to_gregorian(jdn):
    a = jdn + 32044
    b = floor_div(4*a + 3, 146097)
    c = a - floor_div(146097*b, 4)
    d = floor_div(4*c + 3, 1461)
    e = c - floor_div(1461*d, 4)
    m = floor_div(5*e + 2, 153)
    day   = e - floor_div(153*m + 2, 5) + 1
    month = m + 3 - 12*floor_div(m, 10)
    year  = 100*b + d - 4800 + floor_div(m, 10)
    return (year, month, day)

6. Weekday, day of year · روز هفته و روز سال

پیوند به بخش 6. Weekday, day of year · روز هفته و روز سال
function day_of_week(jdn):     return floor_mod(jdn + 2, 7)       # 0 = Saturday … 6 = Friday
function day_of_year(y, m, d): return days_before_month(m) + d    # 1 … 366

چند نکتهٔ مهم دربارهٔ کدهای بالا:

  • عبارت floor_div(8y + 21, 33) تعداد سال‌های کبیسهٔ قبل از سال y رو طبق فرمول ۳۳ ساله حساب می‌کنه؛ خط بعدی (if y - 1 in CORRECTIONS) اون یک روزی رو که فرمول ساده در سال‌های استثنا زودتر اضافه کرده، کم می‌کنه.
  • توی تابع from_jdn، هر دوتا حلقهٔ while حداکثر یک‌بار اجرا می‌شن. کار این حلقه‌ها اینه که تضمین کنن تابع برای هر ورودی‌ای همیشه سال دقیق رو پیدا می‌کنه و هیچ‌وقت تاریخ نامعتبر برنمی‌گردونه.
  • اگر زبان برنامه‌نویسی شما خودش تایپ تاریخی داره که شمارهٔ روز رو می‌ده (مثل LocalDate.toEpochDay در جاوا، DateOnly.DayNumber در دات‌نت یا Date#jd در روبی)، به جای نوشتن دو تابع بخش ۵ از همون متدهای داخلی زبان استفاده کنید.

مثال قدم‌به‌قدم: تبدیل ۲۱ مارس ۲۰۲۵

پیوند به بخش مثال قدم‌به‌قدم: تبدیل ۲۱ مارس ۲۰۲۵
  1. تبدیل میلادی به شمارهٔ روز: gregorian_to_jdn(2025, 3, 21) = 2460756
  2. تخمین سال شمسی: 1 + floor_div(33 × (2460756 − 1948320) + 3, 12053) = 1 + 1403 = 1404
  3. بررسی روز اول سال ۱۴۰۴: nowruz_jdn(1404) = 1948320 + 365 × 1403 + floor_div(11253, 33) = 1948320 + 512095 + 341 = 2460756 (سال ۱۴۰۳ توی لیست اصلاح نیست)، و چون nowruz_jdn(1405) برابر با 2461121 و بزرگ‌تر از عدد ماست، سال همون ۱۴۰۴ باقی می‌مونه.
  4. پیدا کردن ماه و روز: چندمین روز سال؟ 2460756 − 2460756 = 0 ← ماه = (0 div 31) + 1 = ۱، روز = (0 mod 31) + 1 = ۱
  5. نتیجهٔ نهایی: ۱ فروردین ۱۴۰۴؛ روز هفته هم می‌شه (2460756 + 2) mod 7 = 6 یعنی جمعه. ✔

یک مثال دیگه برای نیمهٔ دوم سال: ۲۳ سپتامبر ۲۰۲۵ ← JDN = 2460942 ← فاصله از اول سال می‌شه 186 ← چون 186 >= 186 هست، می‌ره سراغ ماه‌های ۳۰ روزه و می‌شه ماه ۷، روز ۱ ← ۱ مهر ۱۴۰۴.

بازه (سال شمسی) معادل میلادی وضعیت دقت
۱۳۰۴ تا ۱۴۹۸ ۱۹۲۵ تا ۲۱۲۰ کاملا منطبق با جدول رسمی مرکز تقویم دانشگاه تهران (جدول رسمی سال‌های ۱۲۰۶ تا ۱۴۹۸ رو پوشش می‌ده)
۱۱۷۸ تا ۳۰۰۰ ۱۷۹۹ تا ۳۶۲۱ روزبه‌روز با محاسبهٔ نجومی تست و تایید شده (data/years.csv)
قبل از ۱۱۷۸ یا بعد از ۳۰۰۰ از نظر ریاضی کاملا سازگاره (هر تاریخی به میلادی و برعکس بدون خطا تبدیل می‌شه)، اما تطابق نجومی تضمین نمی‌شه
پیش از ۱۳۰۴ پیش از ۱۹۲۵ در قدیم طول ماه‌ها متغیر بود؛ تاریخ نامه‌ها و اسناد تاریخی قبل از ۱۳۰۴ رو با این فرمول تبدیل نکنید

همیشه فقط یک بازهٔ مشخص و منطقی رو به عنوان ورودی قبول کنید و خارج از اون رو با خطا رد کنید. پیاده‌سازی‌های این مخزن سال‌های ۱۰۰٬۰۰۰− تا ۱۰۰٬۰۰۰ رو قبول می‌کنن (معادل JDN از ۳۴٬۵۷۶٬۲۸۷− تا ۳۸٬۴۷۲٬۵۶۲ و میلادی از 99379-03-29- تا 100622-03-13). این بازه خیلی بزرگ‌تر از هر نیاز واقعی در پروژه‌هاست، اما یک ویژگی فنی عالی داره: تمام اعداد میانی توی فرمول‌های بالا کوچکتر از ۲³¹ باقی می‌مونن (بزرگ‌ترین عدد میانی یعنی 33 × (jdn − EPOCH) حدود ۱٫۲ میلیارد می‌شه)؛ در نتیجه کدها حتی روی سیستم‌های ۳۲ بیتی و اعداد جاوااسکریپت هم بدون سرریز (Overflow) و با دقت کامل کار می‌کنن. همچنین توی کل این بازه، تخمین اولیهٔ سال در تابع from_jdn حداکثر ۱ سال با مقدار واقعی فاصله داره (که روی تک‌تک ۷۳٬۰۴۸٬۸۵۰ روز این بازه تست شده است).

اگر ورودی رو محدود نکنید، این باگ‌ها توی کدتون پیش می‌آد:

  • سرریز اعداد (Overflow): برای شماره‌روزهای خیلی بزرگ، اعداد ۶۴ بیتی سرریز می‌شن و برنامه یا تاریخ اشتباه برمی‌گردونه یا (مثلا در جاوا) توی یک حلقهٔ بی‌نهایت گیر می‌کنه.
  • گرد شدن بی‌سروصدای اعداد در جاوااسکریپت: در جاوااسکریپت اعداد صحیح بزرگ‌تر از ۲⁵³ (Number.MAX_SAFE_INTEGER) بدون اینکه هیچ خطایی بدن، دقت خودشون رو از دست می‌دن و گرد می‌شن!
  • ورودی‌های اعشاری: در زبان‌های داینامیک (مثل JS یا پایتون)، اگر کسی عدد اعشاری مثل 2460756.5 به تابع بده، خروجی هم یک تاریخ اعشاری و عجیب‌وغریب می‌شه!
  • تاریخ‌های میلادی نامعتبر: فرمول استاندارد تبدیل میلادی به JDN، تاریخی مثل 2025-02-30 (۳۰ فوریه!) رو بدون هیچ خطایی قبول می‌کنه و اون رو به 2025-03-02 (۲ مارس) تبدیل می‌کنه؛ پس حتما ورودی میلادی رو هم قبل از تبدیل چک کنید.
  • الگوریتم بورکوفسکی (استفاده‌شده در jalaali-js و کتابخونه‌های مشابه): بر پایهٔ جدولی از ۲۰ نقطهٔ «شکست» کار می‌کنه که چرخه‌های ۳۳ ساله بینشون تکرار می‌شن. خروجی این روش تا ۲۹ اسفند ۱۵۰۲ (مارس ۲۱۲۴) کاملا درسته. اگر الان توی پروژه‌تون از این کتابخونه‌ها استفاده می‌کنید، نیازی نیست فورا عوضش کنید؛ اما اگر می‌خواید تقویم رو از صفر توی زبان جدیدی پیاده‌سازی کنید، الگوریتم همین صفحه ساده‌تر و دقیق‌تره.
  • روش جدول‌محور (Lookup Table): می‌تونید تاریخ نوروز یا وضعیت کبیسه بودن سال‌ها رو برای بازهٔ مورد نیازتون (مثلا از روی فایل data/years.csv) توی یک آرایه نگه دارید. این روش خیلی سریع، ساده و دقیقه، ولی برای تاریخ‌های خارج از جدول نیاز به یک فرمول جایگزین (Fallback) خواهید داشت.
  • محاسبهٔ مستقیم نجومی (پیاده‌سازی‌شده در tools/calendar-data با زبان Rust): این روش «مرجع اصلی حقیقت» است، اما چون برای هر روز یک سری مثلثاتی ۴۹ جمله‌ای رو با اعداد اعشاری حساب می‌کنه و به فرمول‌های ΔT وابسته‌ست، بار پردازشی بالایی داره. از محاسبهٔ نجومی فقط برای تولید داده‌های مرجع و تست استفاده کنید، نه در کد نهایی محصول.