فصل ۳ از ۱۰
الگوریتم
۱۰ دقیقه مطالعهبهروزرسانی
این صفحه مشخصات کامل الگوریتمی رو توضیح میده که توی تمام پیادهسازیهای این مخزن استفاده شده است. این الگوریتم فقط با اعداد صحیح (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) از ۲³¹ کوچکتر میمونه). با این حال، اگر توابعتون ورودیهای دلخواه و کنترلنشده از بیرون میگیرن، بهتره از اعداد ۶۴ بیتی استفاده کنید یا اول محدودهٔ ورودی رو چک کنید.
Constants · ثابتها
پیوند به بخش Constants · ثابتها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.txt1. Leap year · کبیسه
پیوند به بخش 1. Leap year · کبیسه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) < 82. 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 - 14. 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در روبی)، به جای نوشتن دو تابع بخش ۵ از همون متدهای داخلی زبان استفاده کنید.
مثال قدمبهقدم: تبدیل ۲۱ مارس ۲۰۲۵
پیوند به بخش مثال قدمبهقدم: تبدیل ۲۱ مارس ۲۰۲۵- تبدیل میلادی به شمارهٔ روز:
gregorian_to_jdn(2025, 3, 21)= 2460756 - تخمین سال شمسی:
1 + floor_div(33 × (2460756 − 1948320) + 3, 12053)=1 + 1403= 1404 - بررسی روز اول سال ۱۴۰۴:
nowruz_jdn(1404)=1948320 + 365 × 1403 + floor_div(11253, 33)=1948320 + 512095 + 341= 2460756 (سال ۱۴۰۳ توی لیست اصلاح نیست)، و چونnowruz_jdn(1405)برابر با 2461121 و بزرگتر از عدد ماست، سال همون ۱۴۰۴ باقی میمونه. - پیدا کردن ماه و روز: چندمین روز سال؟
2460756 − 2460756 = 0← ماه =(0 div 31) + 1= ۱، روز =(0 mod 31) + 1= ۱ - نتیجهٔ نهایی: ۱ فروردین ۱۴۰۴؛ روز هفته هم میشه
(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 وابستهست، بار پردازشی بالایی داره. از محاسبهٔ نجومی فقط برای تولید دادههای مرجع و تست استفاده کنید، نه در کد نهایی محصول.