# تقویم شمسی (جلالی) در Go

> پیاده‌سازی بدون وابستگی تقویم جلالی (هجری شمسی) در Go: تشخیص سال کبیسه، اعتبارسنجی تاریخ، تبدیل به میلادی و شمارهٔ روز جولیانی، روز هفته و روز سال؛ روزبه‌روز برای سال‌های ۱۱۷۸ تا ۳۰۰۰ راستی‌آزمایی شده. مجوز MIT.

- پیش‌نیاز: Go 1.21+
- تست‌شده با: Go 1.27
- مقایسه‌شده با: ICU4C نسخهٔ 76.1 تا 79.1 (`purego`، بدون نیاز به cgo)
- بررسی‌های اختصاصی: تست با `int` سی‌ودوبیتی، تابع `FromTime` برای تاریخ‌های خیلی دور، `go vet`
- مجوز: MIT
- نسخه: 1.0.0
- دانلود همهٔ فایل‌ها (zip): https://goudarzjafari.com/persian-calendar/files/persian-calendar-go.zip

## شروع سریع

1. فایل کد را کپی یا دانلود کنید و در پروژه‌تان بگذارید (بدون هیچ وابستگی).

2. در صورت تمایل تست‌هایش را هم اجرا کنید. فایل zip همان ساختار پوشه‌ای را دارد که تست‌ها لازم دارند؛ از داخل پوشهٔ زبان: `implementations/go`

   ```sh
   go test ./...
   ```

3. توابع مشترک را صدا بزنید: https://goudarzjafari.com/fa/persian-calendar/implementations/#common-api

## persiancalendar.go

```go
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

// Package persiancalendar implements the Solar Hijri
// (Persian, Jalali, Shamsi) calendar.
//
// Algorithm: 33-year arithmetic rule + 78-year correction table, the
// same algorithm as ICU 77.1+ and ICU4X. It matches the
// astronomical calendar (52.5 E meridian) for 1178-3000 AP. Months are
// 1-based; weekdays 0 = Saturday ... 6 = Friday.
package persiancalendar

import (
	"fmt"
	"time"
)

// Date is a Persian calendar date.
type Date struct {
	Year  int
	Month int // 1 = Farvardin ... 12 = Esfand
	Day   int
}

const (
	// VerifiedMinYear and VerifiedMaxYear bound the years checked against the astronomical calendar.
	VerifiedMinYear = 1178
	VerifiedMaxYear = 3000

	// MinYear..MaxYear and MinJdn..MaxJdn are the accepted input range. Within it every
	// intermediate value fits in 32 bits, so the package is also safe where int is 32 bits.
	MinYear = -100000
	MaxYear = 100000
	MinJdn  = -34576287 // 1 Farvardin -100000 (Gregorian -99379-03-29)
	MaxJdn  = 38472562  // 29 Esfand 100000 (Gregorian 100622-03-13)

	epochJdn     = 1948320
	unixEpochJdn = 2440588 // JDN of 1970-01-01
)

// Years the 33-year rule calls leap but are not; the next year is leap instead.
var nonLeapCorrection = map[int]bool{}

func init() {
	for _, y := range []int{
		1502, 1601, 1634, 1667, 1700, 1733, 1766, 1799, 1832, 1865, 1898, 1931,
		1964, 1997, 2030, 2059, 2063, 2096, 2129, 2158, 2162, 2191, 2195, 2224,
		2228, 2257, 2261, 2290, 2294, 2323, 2327, 2356, 2360, 2389, 2393, 2422,
		2426, 2455, 2459, 2488, 2492, 2521, 2525, 2554, 2558, 2587, 2591, 2620,
		2624, 2653, 2657, 2686, 2690, 2719, 2723, 2748, 2752, 2756, 2781, 2785,
		2789, 2818, 2822, 2847, 2851, 2855, 2880, 2884, 2888, 2913, 2917, 2921,
		2946, 2950, 2954, 2979, 2983, 2987,
	} {
		nonLeapCorrection[y] = true
	}
}

var (
	monthNamesFa   = [12]string{"فروردین", "اردیبهشت", "خرداد", "تیر", "مرداد", "شهریور", "مهر", "آبان", "آذر", "دی", "بهمن", "اسفند"}
	monthNamesEn   = [12]string{"Farvardin", "Ordibehesht", "Khordad", "Tir", "Mordad", "Shahrivar", "Mehr", "Aban", "Azar", "Dey", "Bahman", "Esfand"}
	weekdayNamesFa = [7]string{"شنبه", "یکشنبه", "دوشنبه", "سه‌شنبه", "چهارشنبه", "پنجشنبه", "جمعه"}
	weekdayNamesEn = [7]string{"Saturday", "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"}
)

// The name tables are returned as array values (copies), so callers cannot change them.

// MonthNamesFa returns the Persian month names; index 0 is Farvardin.
func MonthNamesFa() [12]string { return monthNamesFa }

// MonthNamesEn returns the CLDR English month names; index 0 is Farvardin.
func MonthNamesEn() [12]string { return monthNamesEn }

// WeekdayNamesFa returns the Persian weekday names; index 0 is Saturday.
func WeekdayNamesFa() [7]string { return weekdayNamesFa }

// WeekdayNamesEn returns the English weekday names; index 0 is Saturday.
func WeekdayNamesEn() [7]string { return weekdayNamesEn }

// Go's / and % truncate toward zero; the formulas need floor semantics.
func floorDiv(a, b int) int {
	q := a / b
	if (a%b != 0) && ((a < 0) != (b < 0)) {
		q--
	}
	return q
}

func floorMod(a, b int) int { return a - b*floorDiv(a, b) }

// IsLeapYear reports whether the Persian year has 366 days. It never overflows:
// (25*year + 11) mod 33 is computed from year mod 33.
func IsLeapYear(year int) bool {
	if year >= 1502 && year <= 2988 {
		if nonLeapCorrection[year] {
			return false
		}
		if nonLeapCorrection[year-1] {
			return true
		}
	}
	return floorMod(25*floorMod(year, 33)+11, 33) < 8
}

// DaysInMonth returns 29, 30 or 31. It panics if month is not 1..12 (a programming error;
// use IsValid to check user input).
func DaysInMonth(year, month int) int {
	switch {
	case month < 1 || month > 12:
		panic(fmt.Sprintf("month out of range: %d", month))
	case month <= 6:
		return 31
	case month <= 11:
		return 30
	case IsLeapYear(year):
		return 30
	default:
		return 29
	}
}

// IsValid reports whether year/month/day is a real Persian date in MinYear..MaxYear.
func IsValid(year, month, day int) bool {
	return year >= MinYear && year <= MaxYear && month >= 1 && month <= 12 && day >= 1 && day <= DaysInMonth(year, month)
}

func nowruzJdn(year int) int {
	jdn := epochJdn + 365*(year-1) + floorDiv(8*year+21, 33)
	if nonLeapCorrection[year-1] {
		jdn--
	}
	return jdn
}

func daysBeforeMonth(month int) int {
	if month <= 7 {
		return 31 * (month - 1)
	}
	return 30*(month-1) + 6
}

// ToJdn returns the Julian Day Number of a Persian date.
func ToJdn(year, month, day int) (int, error) {
	if !IsValid(year, month, day) {
		return 0, fmt.Errorf("invalid Persian date: %d/%d/%d", year, month, day)
	}
	return nowruzJdn(year) + daysBeforeMonth(month) + day - 1, nil
}

// FromJdn returns the Persian date of a Julian Day Number in MinJdn..MaxJdn.
func FromJdn(jdn int) (Date, error) {
	if jdn < MinJdn || jdn > MaxJdn {
		return Date{}, fmt.Errorf("jdn out of range [%d, %d]: %d", MinJdn, MaxJdn, jdn)
	}
	year := 1 + floorDiv(33*(jdn-epochJdn)+3, 12053)
	for jdn >= nowruzJdn(year+1) {
		year++
	}
	for jdn < nowruzJdn(year) {
		year--
	}
	doy := jdn - nowruzJdn(year) // 0-based
	if doy < 186 {
		return Date{year, doy/31 + 1, doy%31 + 1}, nil
	}
	doy -= 186
	return Date{year, doy/30 + 7, doy%30 + 1}, nil
}

// FromTime returns the Persian date of t in t's own location.
// Use t.In(loc) first to choose the time zone (e.g. Asia/Tehran).
func FromTime(t time.Time) (Date, error) {
	y, m, d := t.Date()
	civil := time.Date(y, m, d, 0, 0, 0, 0, time.UTC)
	jdn := civil.Unix()/86400 + unixEpochJdn // int64: checked before converting to int
	if jdn < MinJdn || jdn > MaxJdn {
		return Date{}, fmt.Errorf("date out of range: %s", civil.Format("2006-01-02"))
	}
	return FromJdn(int(jdn))
}

// ToTime returns midnight of the Persian date in loc.
func ToTime(year, month, day int, loc *time.Location) (time.Time, error) {
	jdn, err := ToJdn(year, month, day)
	if err != nil {
		return time.Time{}, err
	}
	g := time.Unix(int64(jdn-unixEpochJdn)*86400, 0).UTC()
	return time.Date(g.Year(), g.Month(), g.Day(), 0, 0, 0, 0, loc), nil
}

// Weekday returns 0 = Saturday (شنبه) ... 6 = Friday (جمعه).
func Weekday(year, month, day int) (int, error) {
	jdn, err := ToJdn(year, month, day)
	if err != nil {
		return 0, err
	}
	return floorMod(jdn+2, 7), nil
}

// DayOfYear returns 1 ... 365/366.
func DayOfYear(year, month, day int) (int, error) {
	if !IsValid(year, month, day) {
		return 0, fmt.Errorf("invalid Persian date: %d/%d/%d", year, month, day)
	}
	return daysBeforeMonth(month) + day, nil
}
```

## persiancalendar_test.go

```go
// Copyright (C) 2026 Goudarz Jafari <hi@goudarzjafari.com>
// SPDX-License-Identifier: MIT

package persiancalendar

import (
	"math"
	"os"
	"strconv"
	"strings"
	"testing"
	"time"
)

func csv(t *testing.T, name string) [][]string {
	b, err := os.ReadFile("../../data/" + name)
	if err != nil {
		t.Fatal(err)
	}
	var rows [][]string
	for _, l := range strings.Split(strings.TrimSpace(string(b)), "\n")[1:] {
		rows = append(rows, strings.Split(l, ","))
	}
	return rows
}

func atoi(s string) int { n, _ := strconv.Atoi(s); return n }

func must(v int, err error) int {
	if err != nil {
		panic(err)
	}
	return v
}

// fj and ft unwrap FromJdn / FromTime for inputs that are known to be valid.
func fj(jdn int) Date      { return mustDate(FromJdn(jdn)) }
func ft(tm time.Time) Date { return mustDate(FromTime(tm)) }

func mustDate(d Date, err error) Date {
	if err != nil {
		panic(err)
	}
	return d
}

// Limits: exact boundaries, and fast rejection of anything outside (no hang, no overflow).
func TestLimits(t *testing.T) {
	if must(ToJdn(MinYear, 1, 1)) != MinJdn || must(ToJdn(MaxYear, 12, 29)) != MaxJdn {
		t.Fatal("limits")
	}
	if mustDate(FromJdn(MinJdn)) != (Date{MinYear, 1, 1}) || mustDate(FromJdn(MaxJdn)) != (Date{MaxYear, 12, 29}) {
		t.Fatal("limit dates")
	}
	for _, bad := range []int{MinJdn - 1, MaxJdn + 1, math.MaxInt, math.MinInt, math.MaxInt / 2} {
		if _, err := FromJdn(bad); err == nil {
			t.Fatalf("FromJdn(%d) should fail", bad)
		}
	}
	for _, bad := range []int{MinYear - 1, MaxYear + 1, math.MaxInt, math.MinInt} {
		if IsValid(bad, 1, 1) {
			t.Fatalf("IsValid(%d)", bad)
		}
		if _, err := ToJdn(bad, 1, 1); err == nil {
			t.Fatalf("ToJdn(%d) should fail", bad)
		}
		_ = IsLeapYear(bad) // must not panic or overflow
	}
	if IsLeapYear(math.MaxInt) != IsLeapYear(math.MaxInt%33+33*1000) {
		t.Fatal("IsLeapYear must reduce mod 33 without overflow")
	}
	for _, far := range []time.Time{time.Date(math.MaxInt32, 1, 1, 0, 0, 0, 0, time.UTC), time.Date(math.MinInt32, 1, 1, 0, 0, 0, 0, time.UTC)} {
		if _, err := FromTime(far); err == nil {
			t.Fatalf("FromTime(%v) should fail", far)
		}
	}
	names := MonthNamesFa()
	names[0] = "X"
	if MonthNamesFa()[0] != "فروردین" {
		t.Fatal("name tables must not be shared")
	}
}

func TestYears(t *testing.T) {
	for _, r := range csv(t, "years.csv") {
		y, leap := atoi(r[0]), r[1] == "1"
		if IsLeapYear(y) != leap {
			t.Fatalf("leap %d", y)
		}
		g, _ := ToTime(y, 1, 1, time.UTC)
		if g.Format("2006-01-02") != r[3] {
			t.Fatalf("nowruz %d: %s != %s", y, g.Format("2006-01-02"), r[3])
		}
		if must(ToJdn(y, 1, 1)) != atoi(r[4]) || must(Weekday(y, 1, 1)) != atoi(r[5]) {
			t.Fatalf("jdn/weekday %d", y)
		}
		// every day of the year against the ground truth, both directions
		for doy := 0; doy < atoi(r[2]); doy++ {
			m, d := doy/31+1, doy%31+1
			if doy >= 186 {
				m, d = (doy-186)/30+7, (doy-186)%30+1
			}
			jdn := atoi(r[4]) + doy
			if fj(jdn) != (Date{y, m, d}) || must(ToJdn(y, m, d)) != jdn {
				t.Fatalf("%d/%d/%d (JDN %d)", y, m, d, jdn)
			}
		}
	}
}

func TestVectors(t *testing.T) {
	for _, r := range csv(t, "test-vectors.csv") {
		p := Date{atoi(r[0]), atoi(r[1]), atoi(r[2])}
		g := time.Date(atoi(r[3]), time.Month(atoi(r[4])), atoi(r[5]), 0, 0, 0, 0, time.UTC)
		if ft(g) != p {
			t.Fatalf("FromTime %v", g)
		}
		if tt, _ := ToTime(p.Year, p.Month, p.Day, time.UTC); !tt.Equal(g) {
			t.Fatalf("ToTime %v", p)
		}
		if must(ToJdn(p.Year, p.Month, p.Day)) != atoi(r[6]) || fj(atoi(r[6])) != p {
			t.Fatalf("jdn %v", p)
		}
		if must(Weekday(p.Year, p.Month, p.Day)) != atoi(r[7]) {
			t.Fatalf("weekday %v", p)
		}
	}
}

func TestEveryDay(t *testing.T) {
	first := must(ToJdn(VerifiedMinYear, 1, 1))
	last := must(ToJdn(VerifiedMaxYear, 12, DaysInMonth(VerifiedMaxYear, 12)))
	prev := fj(first - 1)
	for jdn := first; jdn <= last; jdn++ {
		d := fj(jdn)
		if !IsValid(d.Year, d.Month, d.Day) || must(ToJdn(d.Year, d.Month, d.Day)) != jdn {
			t.Fatalf("round trip %d", jdn)
		}
		consecutive := (d.Day == prev.Day+1 && d.Month == prev.Month && d.Year == prev.Year) ||
			(d.Day == 1 && ((d.Month == prev.Month+1 && d.Year == prev.Year) ||
				(d.Month == 1 && prev.Month == 12 && d.Year == prev.Year+1)))
		if !consecutive {
			t.Fatalf("not consecutive at %d", jdn)
		}
		prev = d
	}
}

// Extrapolated years: years <= 0 make intermediate values negative (floor division matters).
func TestExtrapolatedYears(t *testing.T) {
	if must(ToJdn(-1000, 1, 1)) != 1582713 || must(ToJdn(0, 1, 1)) != 1947955 || must(ToJdn(4000, 1, 1)) != 3408925 {
		t.Fatal("fixed values")
	}
	if fj(0) != (Date{-5334, 9, 3}) || must(Weekday(-1000, 1, 1)) != 1 || !IsLeapYear(-3) || IsLeapYear(-1000) {
		t.Fatal("fixed values")
	}
	for _, r := range [][2]int{{-1000, 1177}, {3001, 4000}} {
		first := must(ToJdn(r[0], 1, 1))
		last := must(ToJdn(r[1], 12, DaysInMonth(r[1], 12)))
		prev := fj(first - 1)
		for jdn := first; jdn <= last; jdn++ {
			d := fj(jdn)
			if !IsValid(d.Year, d.Month, d.Day) || must(ToJdn(d.Year, d.Month, d.Day)) != jdn {
				t.Fatalf("round trip %d", jdn)
			}
			consecutive := (d.Day == prev.Day+1 && d.Month == prev.Month && d.Year == prev.Year) ||
				(d.Day == 1 && ((d.Month == prev.Month+1 && d.Year == prev.Year) ||
					(d.Month == 1 && prev.Month == 12 && d.Year == prev.Year+1)))
			if !consecutive {
				t.Fatalf("not consecutive at %d", jdn)
			}
			prev = d
		}
	}
}

func TestValidationAndKnownDates(t *testing.T) {
	cases := []struct {
		y, m, d int
		ok      bool
	}{{1403, 12, 30, true}, {1404, 12, 30, false}, {1404, 6, 31, true}, {1404, 7, 31, false},
		{1404, 13, 1, false}, {1404, 0, 1, false}, {1404, 1, 0, false}}
	for _, c := range cases {
		if IsValid(c.y, c.m, c.d) != c.ok {
			t.Fatalf("IsValid %v", c)
		}
	}
	if _, err := ToJdn(1404, 12, 30); err == nil {
		t.Fatal("expected error")
	}
	if ft(time.Date(2025, 3, 21, 0, 0, 0, 0, time.UTC)) != (Date{1404, 1, 1}) {
		t.Fatal("2025-03-21")
	}
	if ft(time.Date(1979, 2, 11, 0, 0, 0, 0, time.UTC)) != (Date{1357, 11, 22}) {
		t.Fatal("1979-02-11")
	}
	// Time zone matters: 2025-03-20T21:00Z is 1 Farvardin in Tehran, 30 Esfand in UTC.
	instant := time.Date(2025, 3, 20, 21, 0, 0, 0, time.UTC)
	if tehran, err := time.LoadLocation("Asia/Tehran"); err == nil {
		if ft(instant.In(tehran)) != (Date{1404, 1, 1}) {
			t.Fatal("Tehran time zone")
		}
	}
	if ft(instant) != (Date{1403, 12, 30}) {
		t.Fatal("UTC")
	}
	if WeekdayNamesEn()[must(Weekday(1404, 1, 1))] != "Friday" || must(DayOfYear(1404, 7, 1)) != 187 {
		t.Fatal("weekday/day of year")
	}
}

// Every year MinYear..MaxYear: years are contiguous, first and last day round-trip, and the leap
// years sit where every other implementation (and ICU 77.1+) puts them (checksums). int64 sums:
// the Nowruz sum does not fit in a 32-bit int.
func TestEveryYearOfTheFullRange(t *testing.T) {
	expected := MinJdn
	var leaps, nowruzSum int64
	for y := MinYear; y <= MaxYear; y++ {
		nowruz := must(ToJdn(y, 1, 1))
		leap := 0
		if IsLeapYear(y) {
			leap = 1
		}
		if nowruz != expected || fj(nowruz) != (Date{y, 1, 1}) || DaysInMonth(y, 12) != 29+leap ||
			fj(nowruz+364+leap) != (Date{y, 12, 29 + leap}) {
			t.Fatalf("year %d", y)
		}
		leaps += int64(leap)
		nowruzSum += int64(nowruz)
		expected = nowruz + 365 + leap
	}
	if expected-1 != MaxJdn || leaps != 48485 || nowruzSum != 389592978180 {
		t.Fatalf("checksums: last %d, leaps %d, sum %d", expected-1, leaps, nowruzSum)
	}
}
```

## go.mod

```
module github.com/Goudarz/PersianCalendar/implementations/go

go 1.21
```

---

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