Standard library · Time and concurrency

calendar

The Jalali, Hijri and Gregorian calendars: conversion, day arithmetic, month names and time zones.

import calendar

This package works with three calendars: Jalali (Solar Hijri, the official calendar of Iran and Afghanistan), Hijri (lunar) and Gregorian. A date is a plain struct of year, month and day, and each calendar has its own conversion, validation, day arithmetic and month name functions.

The Hijri calendar here is arithmetic: months alternate between 30 and 29 days and are not adjusted by sighting the moon, so a date can be one day off from the official calendar of a given country.

There are three ways to turn an instant into a date: EpochToJalali and its siblings use the machine local time, WallClockJalali takes a fixed time zone such as Tehran, and LoadZone covers zones that observe daylight saving.

Use it to show dates the way people in Iran, Afghanistan or the Arab world read them, to take a Jalali date from a form, and to turn a meeting time in one city into the time in another. Instants, durations and the clock itself are in time; store instants there and convert to a calendar only for display. For Persian digits in the output, see i18n.

The things people get wrong:

  • Taking today's date on a server with TodayJalali or EpochToJalali. Those use the machine's zone, and a server set to UTC is still on yesterday until 03:30 in Tehran. Use WallClockJalali(time.Now(), TZTehran()).
  • Mixing the two weekday numberings. JalaliWeekday takes a Julian day number and counts from Saturday as 0; Weekday, WeekdayJalali and the other Weekday... functions count from Sunday as 0.
  • Converting unchecked input. The conversions do not validate, so 31 Esfand or month 13 gives a wrong date instead of an error. Check with IsValidJalaliDate and its siblings first.
  • Expecting the Hijri dates to match an official calendar to the day, or the fixed TZLondon and TZNewYork zones to follow daylight saving. They do not; use LoadZone for that.

The Jalali conversion is the standard arithmetic one (as in the jalaali libraries), which works for the years -61 to 3177 and agrees with the official Iranian calendar for the years in use today.

Birthdays and anniversaries in Jalali

Dates are plain structs, so date logic is ordinary code: build the date in the current year, compare it with today using CompareJalali, and move to the next year if it has passed. DaysBetweenJalali counts the days in between, and JalaliToGregorian gives the same day in the other calendar.

calendar-guide-birthday.salam
import calendar

func next birthday(born: calendar.JalaliDate, today: calendar.JalaliDate): calendar.JalaliDate:
    mut target year := today.year
    mut target day := born.day
    if born.month == 12 and target day == 30 and not calendar.IsLeapJalali(target year):
        target day = 29
    end
    mut next := calendar.JalaliDate { year = target year, month = born.month, day = target day }
    if calendar.CompareJalali(next, today) < 0:
        target year++
        target day = born.day
        if born.month == 12 and target day == 30 and not calendar.IsLeapJalali(target year):
            target day = 29
        end
        next = calendar.JalaliDate { year = target year, month = born.month, day = target day }
    end
    ret next
end

func main:
    today := calendar.JalaliDate { year = 1405, month = 7, day = 25 }
    born := calendar.JalaliDate { year = 1370, month = 9, day = 3 }
    mut age := today.year - born.year
    birthday now := calendar.JalaliDate { year = today.year, month = born.month, day = born.day }
    if calendar.CompareJalali(birthday now, today) > 0:
        age--
    end
    next := next birthday(born, today)
    println "age:", age
    println "next birthday:", calendar.FormatJalali(next), "(" + calendar.JalaliMonthNameEn(next.month) + ")"
    println "days to go:", calendar.DaysBetweenJalali(today, next)
    println "in the Gregorian calendar:", calendar.FormatGregorian(calendar.JalaliToGregorian(next))
    leap := calendar.JalaliDate { year = 1403, month = 12, day = 30 }
    println "born on 30 Esfand 1403, celebrates in 1405 on:", calendar.FormatJalali(next birthday(leap, today))
end
Outputage: 34 next birthday: 1405-09-03 (Azar) days to go: 38 in the Gregorian calendar: 2026-11-24 born on 30 Esfand 1403, celebrates in 1405 on: 1405-12-29

One case needs care: 30 Esfand exists only in leap years. Before building a date in another year, check it with IsLeapJalali or IsValidJalaliDate; the example moves such a birthday to 29 Esfand. AddYearsJalali and AddMonthsJalali do the same clamping for you when you only need to move a date.

Drawing a month

A month view needs two numbers: the weekday of the first day and the length of the month. JalaliWeekday numbers the days from Saturday as 0, which is how Persian calendars are laid out, and DaysInJalaliMonth gives the length.

calendar-guide-month.salam
import calendar
import str

func main:
    shown year := 1405
    shown month := 7
    first := calendar.JalaliDate { year = shown year, month = shown month, day = 1 }
    println calendar.JalaliMonthNameEn(shown month), shown year
    println "Sa Su Mo Tu We Th Fr"
    offset := calendar.JalaliWeekday(calendar.JalaliToJDN(first))
    mut line := ""
    repeat offset:
        line += "   "
    end
    days := calendar.DaysInJalaliMonth(shown year, shown month)
    repeat 1 to days in d:
        if d < 10:
            line += " "
        end
        line += str.FromInt(d)
        if (offset + d) % 7 == 0:
            println line
            line = ""
        else:
            line += " "
        end
    end
    if line != "":
        println line.Trim()
    end
    println "starts on", calendar.FormatGregorianLongEn(calendar.JalaliToGregorian(first))
end
OutputMehr 1405 Sa Su Mo Tu We Th Fr 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 starts on September 23, 2026

For a week that starts on Sunday or Monday, use WeekdayJalali or WeekdayGregorian instead, which number from Sunday as 0, and shift by the day you want first.

A Hijri month in the other calendars

For Ramadan or Muharram you usually want the Hijri dates translated into Gregorian and Jalali ones. DaysInHijriMonth gives the length of the month and AddDaysHijri walks from its first day to its last.

calendar-guide-ramadan.salam
import calendar

func main:
    start := calendar.HijriDate { year = 1448, month = 9, day = 1 }
    days := calendar.DaysInHijriMonth(start.year, start.month)
    last := calendar.AddDaysHijri(start, days - 1)
    eid := calendar.AddDaysHijri(last, 1)
    println calendar.HijriMonthNameEn(start.month), start.year, "has", days, "days"
    println "first day:", calendar.FormatGregorian(calendar.HijriToGregorian(start)), "=", calendar.FormatJalali(calendar.HijriToJalali(start))
    println "last day: ", calendar.FormatGregorian(calendar.HijriToGregorian(last)), "=", calendar.FormatJalali(calendar.HijriToJalali(last))
    println "Eid:      ", calendar.FormatGregorian(calendar.HijriToGregorian(eid)), calendar.WeekdayNameEn(calendar.WeekdayHijri(eid))
    println "in Arabic:", calendar.FormatHijriLongAr(eid)
end
OutputRamadan 1448 has 30 days first day: 2027-02-08 = 1405-11-19 last day: 2027-03-09 = 1405-12-18 Eid: 2027-03-10 Wednesday in Arabic: 1 شوال 1448

Remember that this is the arithmetic Hijri calendar. The official start of a month depends on sighting the moon and can be a day earlier or later, and differs between countries, so show these dates as an estimate.

One meeting, several cities

To schedule across time zones, turn the local date and time in one zone into an instant with ZonedToEpoch, then show that instant in each other zone. LoadZone reads the system's time zone database, so daylight saving is handled: London is on GMT on 25 March 2026 and on BST a week later, while New York had already moved to EDT.

calendar-guide-meeting.salam
import calendar

func show(label: str, epoch: i64, zone name: str):
    mut z := calendar.LoadZone(zone name)
    tz := calendar.TimeZoneAt(z, epoch)
    d := calendar.WallClockGregorian(epoch, tz)
    t := calendar.WallClockTime(epoch, tz)
    println label, calendar.FormatGregorian(d), calendar.FormatClockTime(t), calendar.ZoneAbbrevAt(z, epoch)
    calendar.FreeZone(z)
end

func main:
    mut tehran := calendar.LoadZone("Asia/Tehran")
    meeting day := calendar.GregorianDate { year = 2026, month = 3, day = 25 }
    at := calendar.ClockTime { hour = 18, minute = 30 }
    meeting := calendar.ZonedToEpoch(meeting day, at, tehran)
    calendar.FreeZone(tehran)
    show("Tehran:  ", meeting, "Asia/Tehran")
    show("London:  ", meeting, "Europe/London")
    show("New York:", meeting, "America/New_York")
    show("Tokyo:   ", meeting, "Asia/Tokyo")
    show("one week later in London:", meeting + 7 * 86400, "Europe/London")
end
OutputTehran: 2026-03-25 18:30:00 +0330 London: 2026-03-25 15:00:00 GMT New York: 2026-03-25 11:00:00 EDT Tokyo: 2026-03-26 00:00:00 JST one week later in London: 2026-04-01 16:00:00 BST

LoadZone needs the zone files that Linux and macOS keep in /usr/share/zoneinfo; check ok on the result. For a zone with a fixed offset, such as Tehran since Iran stopped daylight saving, TZTehran() or FixedOffsetZone with WallClockJalali needs no files at all. Free a loaded zone with FreeZone when you are done with it.

Which function for which job

JobUse
Convert between calendarsGregorianToJalali, JalaliToGregorian, HijriToJalali and the rest
Today's dateTodayJalali, TodayGregorian, TodayHijri
A date from a stored instantWallClockJalali(epoch, TZTehran()), or EpochToJalali for local time
Move a dateAddDaysJalali, AddMonthsJalali, AddYearsJalali
Compare or count daysCompareJalali, DaysBetweenJalali
Check user inputIsValidJalaliDate, IsValidGregorianDate, IsValidHijriDate
Show a dateFormatJalali, FormatJalaliLongFa, FormatHijriLongAr, FormatGregorianLongEn
Zones with daylight savingLoadZone, ZonedToEpoch, TimeZoneAt

Types

TimeZone

struct TimeZone
A time zone with a fixed offset from UTC.
NameTypeDescription
namestr = "UTC"The zone name, such as Asia/Tehran.
offset_minutesint = 0The offset from UTC in minutes; 210 for Tehran.
calendar-TimeZone.salam
import calendar

func main:
    t := 1710943509
    tehran := calendar.TZTehran()
    println tehran.name, tehran.offset_minutes
    println calendar.FormatJalali(calendar.WallClockJalali(t, tehran)), calendar.FormatClockTime(calendar.WallClockTime(t, tehran))
    println calendar.FormatGregorian(calendar.WallClockGregorian(t, calendar.TZTokyo())), calendar.FormatClockTime(calendar.WallClockTime(t, calendar.TZTokyo()))
    println calendar.FormatHijri(calendar.WallClockHijri(t, calendar.TZMecca()))
    each zone in [calendar.TZUTC(), calendar.TZKabul(), calendar.TZRiyadh(), calendar.TZDubai(), calendar.TZIstanbul(), calendar.TZLondon(), calendar.TZNewYork()]:
        println zone.name, zone.offset_minutes, calendar.FormatClockTime(calendar.WallClockTime(t, zone))
    end
    g := calendar.GregorianDate { year = 2024, month = 3, day = 20 }
    c := calendar.ClockTime { hour = 23, minute = 0, second = 0 }
    println calendar.ZonedGregorianToEpoch(g, c, tehran)
    println calendar.FormatGregorian(calendar.ConvertZonedGregorian(g, c, tehran, calendar.TZTokyo())), calendar.FormatClockTime(calendar.ConvertZonedTime(g, c, tehran, calendar.TZTokyo()))
    fixed := calendar.FixedOffsetZone("UTC+05:30", 330)
    println fixed.name, calendar.FormatClockTime(calendar.WallClockTime(t, fixed))
    local := calendar.TZLocal(t)
    println local.name, local.offset_minutes == calendar.LocalOffsetMinutes(t)
end
OutputAsia/Tehran 210 1403-01-01 17:35:09 2024-03-20 23:05:09 1445-09-10 UTC 0 14:05:09 Asia/Kabul 270 18:35:09 Asia/Riyadh 180 17:05:09 Asia/Dubai 240 18:05:09 Europe/Istanbul 180 17:05:09 Europe/London 0 14:05:09 America/New_York -300 09:05:09 1710963000 2024-03-21 04:30:00 UTC+05:30 19:35:09 Local true

GregorianDate

struct GregorianDate
A Gregorian date.
NameTypeDescription
yearint = 1970The year.
monthint = 1The month, from 1.
dayint = 1The day of the month, from 1.
calendar-Convert.salam
import calendar

func main:
    g := calendar.GregorianDate { year = 2024, month = 3, day = 20 }
    j := calendar.GregorianToJalali(g)
    h := calendar.GregorianToHijri(g)
    println calendar.FormatGregorian(g), calendar.FormatJalali(j), calendar.FormatHijri(h)
    println calendar.FormatJalaliLongFa(j)
    println calendar.FormatHijriLongFa(h)
    println calendar.FormatHijriLongAr(h)
    println calendar.FormatGregorianLongEn(g)
    println calendar.FormatGregorian(calendar.JalaliToGregorian(calendar.JalaliDate { year = 1403, month = 1, day = 1 }))
    println calendar.FormatGregorian(calendar.HijriToGregorian(calendar.HijriDate { year = 1445, month = 9, day = 1 }))
    println calendar.FormatHijri(calendar.JalaliToHijri(j)), calendar.FormatJalali(calendar.HijriToJalali(h))
    d := calendar.GregorianToJDN(g)
    println d, calendar.JalaliToJDN(j), calendar.HijriToJDN(h)
    println calendar.FormatGregorian(calendar.JDNToGregorian(d + 1)), calendar.FormatJalali(calendar.JDNToJalali(d + 1)), calendar.FormatHijri(calendar.JDNToHijri(d + 1))
end
Output2024-03-20 1403-01-01 1445-09-10 1 فروردین 1403 10 رمضان 1445 10 رمضان 1445 March 20, 2024 2024-03-20 2024-03-11 1445-09-10 1403-01-01 2460390 2460390 2460390 2024-03-21 1403-01-02 1445-09-11

JalaliDate

struct JalaliDate
A Jalali, Solar Hijri, date.
NameTypeDescription
yearint = 1The year.
monthint = 1The month, from 1 (Farvardin).
dayint = 1The day of the month, from 1.

The example for this item is shown with the ones above: calendar-Convert.salam

HijriDate

struct HijriDate
A Hijri, lunar, date.
NameTypeDescription
yearint = 1The year.
monthint = 1The month, from 1 (Muharram).
dayint = 1The day of the month, from 1.

The example for this item is shown with the ones above: calendar-Convert.salam

ClockTime

struct ClockTime
A time of day.
NameTypeDescription
hourint = 0The hour, 0 to 23.
minuteint = 0The minute.
secondint = 0The second.
calendar-Epoch.salam
import calendar
import time

func main:
    t := 1710943509
    zone := calendar.TZLocal(t)
    g := calendar.EpochToGregorian(t)
    println calendar.CompareGregorian(g, calendar.WallClockGregorian(t, zone)) == 0
    println calendar.CompareJalali(calendar.EpochToJalali(t), calendar.WallClockJalali(t, zone)) == 0
    println calendar.CompareHijri(calendar.EpochToHijri(t), calendar.WallClockHijri(t, zone)) == 0
    println calendar.FormatClockTime(calendar.EpochToClockTime(t)) == calendar.FormatClockTime(calendar.WallClockTime(t, zone))
    j := calendar.JalaliDate { year = 1403, month = 1, day = 1 }
    println calendar.JalaliToUnixUTC(j, 14, 5, 9) == t
    println calendar.GregorianToUnixUTC(calendar.GregorianDate { year = 2024, month = 3, day = 20 }, 14, 5, 9)
    println calendar.HijriToUnixUTC(calendar.HijriDate { year = 1445, month = 9, day = 10 }, 0, 0, 0)
    println calendar.CompareGregorian(calendar.TodayGregorian(), calendar.EpochToGregorian(time.Now())) >= 0, calendar.TodayGregorian().year >= 2024, calendar.TodayJalali().year >= 1403, calendar.TodayHijri().year >= 1445
    c := calendar.NowClockTime()
    println c.hour < 24, c.minute < 60, c.second < 61
end
Outputtrue true true true true 1710943509 1710892800 true true true true true true true

Zone

struct Zone
A full time zone from the zone database (tzdata), with its history of offsets and daylight saving.
NameTypeDescription
namestr = "UTC"The zone name.
okbool = falseWhether the zone loaded.
type_offsetVectorThe offset of each time type, in seconds.
type_isdstVectorWhether each type is daylight saving.
type_abbrevVectorThe abbreviation of each type, such as EST.
timesVectorThe instants at which the offset changes.
type_atVectorThe time type in force after each change.
base_typeint = 0The type in force before the first change.
rulePosixTZThe POSIX rule for the years after the last recorded change.
calendar-Zone.salam
import calendar

func main:
    mut z := calendar.LoadZone("America/New_York")
    println z.name, z.ok
    winter := 1704067200
    summer := 1719792000
    println calendar.ZoneOffsetMinutes(z, winter), calendar.ZoneOffsetMinutes(z, summer), calendar.ZoneOffsetSeconds(z, summer)
    println calendar.ZoneIsDST(z, winter), calendar.ZoneIsDST(z, summer)
    println calendar.ZoneAbbrevAt(z, winter), calendar.ZoneAbbrevAt(z, summer)
    tz := calendar.TimeZoneAt(z, summer)
    println tz.name, tz.offset_minutes
    println calendar.ZoneAt("Asia/Tehran", winter).offset_minutes
    e := calendar.ZonedToEpoch(calendar.GregorianDate { year = 2024, month = 6, day = 30 }, calendar.ClockTime { hour = 20 }, z)
    println e == summer
    calendar.FreeZone(z)
    println calendar.LoadZone("Mars/Olympus").ok
    mut l := calendar.LocalZone()
    println l.ok or not l.ok
    calendar.FreeZone(l)
end
OutputAmerica/New_York true -300 -240 -14400 false true EST EDT EDT -240 210 true false true

Functions

FixedOffsetZone

func FixedOffsetZone(name: str, offsetMinutes: int): TimeZone
A zone with a name and an offset of your choosing.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZUTC

func TZUTC(): TimeZone
Coordinated Universal Time, offset zero.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZTehran

func TZTehran(): TimeZone
The Tehran zone, at a fixed 210 minutes (3:30).

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZKabul

func TZKabul(): TimeZone
The Kabul zone, at a fixed 270 minutes (4:30).

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZRiyadh

func TZRiyadh(): TimeZone
The Riyadh zone, at a fixed 180 minutes (3:00).

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZMecca

func TZMecca(): TimeZone
The Mecca zone, the same as Riyadh, at a fixed 180 minutes.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZDubai

func TZDubai(): TimeZone
The Dubai zone, at a fixed 240 minutes (4:00).

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZIstanbul

func TZIstanbul(): TimeZone
The Istanbul zone, at a fixed 180 minutes (3:00).

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZLondon

func TZLondon(): TimeZone
The London zone at a fixed offset of zero. It does not follow daylight saving; use LoadZone for that.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZNewYork

func TZNewYork(): TimeZone
The New York zone at a fixed offset of -300 minutes. It does not follow daylight saving; use LoadZone for that.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZTokyo

func TZTokyo(): TimeZone
The Tokyo zone, at a fixed 540 minutes (9:00).

The example for this item is shown with the ones above: calendar-TimeZone.salam

LocalOffsetMinutes

func LocalOffsetMinutes(epoch: i64): int
The offset of the machine local time from UTC at that instant, in minutes.

The example for this item is shown with the ones above: calendar-TimeZone.salam

TZLocal

func TZLocal(epoch: i64): TimeZone
A zone named Local carrying the local offset at that instant.

The example for this item is shown with the ones above: calendar-TimeZone.salam

WallClockGregorian

func WallClockGregorian(epoch: i64, tz: TimeZone): GregorianDate
The Gregorian date of that instant in the given zone.

The example for this item is shown with the ones above: calendar-TimeZone.salam

WallClockJalali

func WallClockJalali(epoch: i64, tz: TimeZone): JalaliDate
The Jalali date of that instant in the given zone; today's date in Tehran, for instance, wherever the program runs.

The example for this item is shown with the ones above: calendar-TimeZone.salam

WallClockHijri

func WallClockHijri(epoch: i64, tz: TimeZone): HijriDate
The Hijri date of that instant in the given zone.

The example for this item is shown with the ones above: calendar-TimeZone.salam

WallClockTime

func WallClockTime(epoch: i64, tz: TimeZone): ClockTime
The clock time of that instant in the given zone.

The example for this item is shown with the ones above: calendar-TimeZone.salam

ZonedGregorianToEpoch

func ZonedGregorianToEpoch(d: GregorianDate, t: ClockTime, tz: TimeZone): i64
Turns a date and clock time in one zone into an instant, in seconds since the Unix epoch.

The example for this item is shown with the ones above: calendar-TimeZone.salam

ConvertZonedGregorian

func ConvertZonedGregorian(d: GregorianDate, t: ClockTime, from: TimeZone, toTz: TimeZone): GregorianDate
Moves a date and clock time from one zone to another and returns the date there.

The example for this item is shown with the ones above: calendar-TimeZone.salam

ConvertZonedTime

func ConvertZonedTime(d: GregorianDate, t: ClockTime, from: TimeZone, toTz: TimeZone): ClockTime
The same, but returns the clock time in the target zone.

The example for this item is shown with the ones above: calendar-TimeZone.salam

GregorianToJalali

func GregorianToJalali(d: GregorianDate): JalaliDate
Converts a Gregorian date to Jalali, the Solar Hijri calendar.

The example for this item is shown with the ones above: calendar-Convert.salam

JalaliToGregorian

func JalaliToGregorian(d: JalaliDate): GregorianDate
Converts a Jalali date to Gregorian.

The example for this item is shown with the ones above: calendar-Convert.salam

GregorianToHijri

func GregorianToHijri(d: GregorianDate): HijriDate
Converts a Gregorian date to Hijri.

The example for this item is shown with the ones above: calendar-Convert.salam

HijriToGregorian

func HijriToGregorian(d: HijriDate): GregorianDate
Converts a Hijri date to Gregorian.

The example for this item is shown with the ones above: calendar-Convert.salam

JalaliToHijri

func JalaliToHijri(d: JalaliDate): HijriDate
Converts a Jalali date to Hijri.

The example for this item is shown with the ones above: calendar-Convert.salam

HijriToJalali

func HijriToJalali(d: HijriDate): JalaliDate
Converts a Hijri date to Jalali.

The example for this item is shown with the ones above: calendar-Convert.salam

EpochToGregorian

func EpochToGregorian(epoch: i64): GregorianDate
The Gregorian date of that instant in the machine local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

EpochToJalali

func EpochToJalali(epoch: i64): JalaliDate
The Jalali date of that instant in the machine local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

EpochToHijri

func EpochToHijri(epoch: i64): HijriDate
The Hijri date of that instant in the machine local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

EpochToClockTime

func EpochToClockTime(epoch: i64): ClockTime
The clock time of that instant in the machine local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

TodayGregorian

func TodayGregorian(): GregorianDate
Today's Gregorian date in local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

TodayJalali

func TodayJalali(): JalaliDate
Today's Jalali date in local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

TodayHijri

func TodayHijri(): HijriDate
Today's Hijri date in local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

NowClockTime

func NowClockTime(): ClockTime
The current clock time in local time.

The example for this item is shown with the ones above: calendar-Epoch.salam

GregorianToUnixUTC

func GregorianToUnixUTC(d: GregorianDate, hour: int, minute: int, second: int): i64
Turns a Gregorian date and a UTC clock time into seconds since the Unix epoch.

The example for this item is shown with the ones above: calendar-Epoch.salam

JalaliToUnixUTC

func JalaliToUnixUTC(d: JalaliDate, hour: int, minute: int, second: int): i64
Turns a Jalali date and a UTC clock time into seconds since the Unix epoch.

The example for this item is shown with the ones above: calendar-Epoch.salam

HijriToUnixUTC

func HijriToUnixUTC(d: HijriDate, hour: int, minute: int, second: int): i64
Turns a Hijri date and a UTC clock time into seconds since the Unix epoch.

The example for this item is shown with the ones above: calendar-Epoch.salam

FormatGregorian

func FormatGregorian(d: GregorianDate): str
A Gregorian date as 2024-03-20.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatJalali

func FormatJalali(d: JalaliDate): str
A Jalali date as 1403-01-01.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatHijri

func FormatHijri(d: HijriDate): str
A Hijri date as 1445-09-10.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatClockTime

func FormatClockTime(t: ClockTime): str
A clock time as 14:05:09.

The example for this item is shown with the ones above: calendar-Epoch.salam

FormatJalaliLongFa

func FormatJalaliLongFa(d: JalaliDate): str
A Jalali date with the Persian month name, such as 1 فروردین 1403.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatHijriLongAr

func FormatHijriLongAr(d: HijriDate): str
A Hijri date with the Arabic month name.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatHijriLongFa

func FormatHijriLongFa(d: HijriDate): str
A Hijri date with the Persian month name, such as 10 رمضان 1445.

The example for this item is shown with the ones above: calendar-Convert.salam

FormatGregorianLongEn

func FormatGregorianLongEn(d: GregorianDate): str
A Gregorian date in English, such as March 20, 2024.

The example for this item is shown with the ones above: calendar-Convert.salam

JalaliToJDN

func JalaliToJDN(d: JalaliDate): i64
The Julian day number of a Jalali date. The Julian day is a continuous count of days and is what every conversion in this package goes through.

The example for this item is shown with the ones above: calendar-Convert.salam

JDNToJalali

func JDNToJalali(jdn: i64): JalaliDate
The Jalali date of a Julian day number.

The example for this item is shown with the ones above: calendar-Convert.salam

IsLeapJalali

func IsLeapJalali(year: int): bool
True when the Jalali year is a leap year, meaning Esfand has 30 days.
calendar-Jalali.salam
import calendar

func main:
    println calendar.IsLeapJalali(1403), calendar.IsLeapJalali(1404), calendar.DaysInJalaliYear(1403)
    println calendar.DaysInJalaliMonth(1403, 1), calendar.DaysInJalaliMonth(1403, 7), calendar.DaysInJalaliMonth(1403, 12), calendar.DaysInJalaliMonth(1404, 12)
    println calendar.IsValidJalaliDate(1404, 12, 30), calendar.IsValidJalaliDate(1403, 12, 30)
    println calendar.JalaliMonthNameFa(1), calendar.JalaliMonthNameEn(1), calendar.JalaliMonthNameFa(12)
    j := calendar.JalaliDate { year = 1403, month = 6, day = 31 }
    d := calendar.JalaliToJDN(j)
    println calendar.JalaliWeekday(d), calendar.JalaliWeekdayNameFa(calendar.JalaliWeekday(d))
    println calendar.WeekdayJalali(j), calendar.WeekdayNameFa(calendar.WeekdayJalali(j))
    println calendar.FormatJalali(calendar.AddDaysJalali(j, 1)), calendar.FormatJalali(calendar.AddWeeksJalali(j, 2))
    println calendar.FormatJalali(calendar.AddMonthsJalali(j, 1)), calendar.FormatJalali(calendar.AddYearsJalali(j, -1))
    println calendar.FormatJalali(calendar.StartOfMonthJalali(j)), calendar.FormatJalali(calendar.EndOfMonthJalali(calendar.AddMonthsJalali(j, 6)))
    nowruz := calendar.JalaliDate { year = 1404, month = 1, day = 1 }
    println calendar.DaysBetweenJalali(j, nowruz), calendar.CompareJalali(j, nowruz), calendar.CompareJalali(nowruz, nowruz)
end
Outputtrue false 366 31 30 30 29 false true فروردین Farvardin اسفند 0 شنبه 6 شنبه 1403-07-01 1403-07-14 1403-07-30 1402-06-31 1403-06-01 1403-12-30 181 -1 0

DaysInJalaliMonth

func DaysInJalaliMonth(year: int, month: int): int
The number of days in a Jalali month: 31 for the first six, 30 for the next five, and 29 or 30 for Esfand.

The example for this item is shown with the ones above: calendar-Jalali.salam

IsValidJalaliDate

func IsValidJalaliDate(year: int, month: int, day: int): bool
True when the Jalali date exists.

The example for this item is shown with the ones above: calendar-Jalali.salam

JalaliMonthNameFa

func JalaliMonthNameFa(month: int): str
The Persian name of a Jalali month, from 1 (Farvardin) to 12 (Esfand).

The example for this item is shown with the ones above: calendar-Jalali.salam

JalaliMonthNameEn

func JalaliMonthNameEn(month: int): str
The Latin name of a Jalali month, such as Farvardin.

The example for this item is shown with the ones above: calendar-Jalali.salam

JalaliWeekday

func JalaliWeekday(jdn: i64): int
The day of the week of a Julian day number, counted the Iranian way: zero is Saturday through 6 Friday.

The example for this item is shown with the ones above: calendar-Jalali.salam

JalaliWeekdayNameFa

func JalaliWeekdayNameFa(weekday: int): str
The weekday name for a JalaliWeekday number, where zero is Saturday.

The example for this item is shown with the ones above: calendar-Jalali.salam

CompareJalali

func CompareJalali(a: JalaliDate, b: JalaliDate): int
Compares two Jalali dates: -1 when the first is earlier, zero when they are equal, 1 when it is later.

The example for this item is shown with the ones above: calendar-Jalali.salam

GregorianToJDN

func GregorianToJDN(d: GregorianDate): i64
The Julian day number of a Gregorian date.

The example for this item is shown with the ones above: calendar-Convert.salam

JDNToGregorian

func JDNToGregorian(jdn: i64): GregorianDate
The Gregorian date of a Julian day number.

The example for this item is shown with the ones above: calendar-Convert.salam

IsLeapGregorian

func IsLeapGregorian(year: int): bool
True when the Gregorian year is a leap year.
calendar-Gregorian.salam
import calendar

func main:
    println calendar.IsLeapGregorian(2024), calendar.IsLeapGregorian(1900), calendar.DaysInGregorianYear(2024)
    println calendar.DaysInGregorianMonth(2024, 2), calendar.DaysInGregorianMonth(2023, 2), calendar.IsValidGregorianDate(2023, 2, 29)
    g := calendar.GregorianDate { year = 2024, month = 1, day = 31 }
    w := calendar.WeekdayGregorian(g)
    println w, calendar.WeekdayNameEn(w), calendar.WeekdayNameFa(w), calendar.WeekdayNameAr(w)
    println calendar.Weekday(calendar.GregorianToJDN(g)), calendar.GregorianMonthNameEn(1)
    println calendar.FormatGregorian(calendar.AddMonthsGregorian(g, 1)), calendar.FormatGregorian(calendar.AddYearsGregorian(calendar.GregorianDate { year = 2024, month = 2, day = 29 }, 1))
    println calendar.FormatGregorian(calendar.AddDaysGregorian(g, 30)), calendar.FormatGregorian(calendar.AddWeeksGregorian(g, -1))
    println calendar.FormatGregorian(calendar.StartOfMonthGregorian(g)), calendar.FormatGregorian(calendar.EndOfMonthGregorian(calendar.AddMonthsGregorian(g, 1)))
    println calendar.FormatGregorian(calendar.NextWeekdayOnOrAfter(g, 5))
    year_end := calendar.GregorianDate { year = 2024, month = 12, day = 31 }
    println calendar.DaysBetweenGregorian(g, year_end), calendar.CompareGregorian(year_end, g)
end
Outputtrue false 366 29 28 false 3 Wednesday چهارشنبه الأربعاء 3 January 2024-02-29 2025-02-28 2024-03-01 2024-01-24 2024-01-01 2024-02-29 2024-02-02 335 1

DaysInGregorianMonth

func DaysInGregorianMonth(year: int, month: int): int
The number of days in a Gregorian month.

The example for this item is shown with the ones above: calendar-Gregorian.salam

IsValidGregorianDate

func IsValidGregorianDate(year: int, month: int, day: int): bool
True when the Gregorian date exists.

The example for this item is shown with the ones above: calendar-Gregorian.salam

Weekday

func Weekday(jdn: i64): int
The day of the week of a Julian day number: zero is Sunday through 6 Saturday.

The example for this item is shown with the ones above: calendar-Gregorian.salam

WeekdayNameEn

func WeekdayNameEn(weekday: int): str
The English weekday name for a Weekday number.

The example for this item is shown with the ones above: calendar-Gregorian.salam

WeekdayNameFa

func WeekdayNameFa(weekday: int): str
The Persian weekday name for a Weekday number, where zero is Sunday.

The example for this item is shown with the ones above: calendar-Gregorian.salam

WeekdayNameAr

func WeekdayNameAr(weekday: int): str
The Arabic weekday name for a Weekday number.

The example for this item is shown with the ones above: calendar-Gregorian.salam

GregorianMonthNameEn

func GregorianMonthNameEn(month: int): str
The English name of a Gregorian month.

The example for this item is shown with the ones above: calendar-Gregorian.salam

CompareGregorian

func CompareGregorian(a: GregorianDate, b: GregorianDate): int
Compares two Gregorian dates: -1, zero or 1.

The example for this item is shown with the ones above: calendar-Gregorian.salam

AddDaysGregorian

func AddDaysGregorian(d: GregorianDate, n: int): GregorianDate
Adds n days to a Gregorian date; a negative n goes back.

The example for this item is shown with the ones above: calendar-Gregorian.salam

AddWeeksGregorian

func AddWeeksGregorian(d: GregorianDate, n: int): GregorianDate
Adds n weeks to a Gregorian date.

The example for this item is shown with the ones above: calendar-Gregorian.salam

AddMonthsGregorian

func AddMonthsGregorian(d: GregorianDate, n: int): GregorianDate
Adds n months to a Gregorian date; when the day does not exist in the target month, the last day of that month is used.

The example for this item is shown with the ones above: calendar-Gregorian.salam

AddYearsGregorian

func AddYearsGregorian(d: GregorianDate, n: int): GregorianDate
Adds n years to a Gregorian date; a leap day missing from the target year moves to the end of the month.

The example for this item is shown with the ones above: calendar-Gregorian.salam

DaysBetweenGregorian

func DaysBetweenGregorian(from: GregorianDate, toDate: GregorianDate): i64
The number of days from from to toDate; negative when the second is earlier.

The example for this item is shown with the ones above: calendar-Gregorian.salam

StartOfMonthGregorian

func StartOfMonthGregorian(d: GregorianDate): GregorianDate
The first day of the month of a Gregorian date.

The example for this item is shown with the ones above: calendar-Gregorian.salam

EndOfMonthGregorian

func EndOfMonthGregorian(d: GregorianDate): GregorianDate
The last day of the month of a Gregorian date.

The example for this item is shown with the ones above: calendar-Gregorian.salam

DaysInGregorianYear

func DaysInGregorianYear(year: int): int
The number of days in a Gregorian year: 365 or 366.

The example for this item is shown with the ones above: calendar-Gregorian.salam

AddDaysJalali

func AddDaysJalali(d: JalaliDate, n: int): JalaliDate
Adds n days to a Jalali date; a negative n goes back.

The example for this item is shown with the ones above: calendar-Jalali.salam

AddWeeksJalali

func AddWeeksJalali(d: JalaliDate, n: int): JalaliDate
Adds n weeks to a Jalali date.

The example for this item is shown with the ones above: calendar-Jalali.salam

AddMonthsJalali

func AddMonthsJalali(d: JalaliDate, n: int): JalaliDate
Adds n months to a Jalali date; when the day does not exist in the target month, the last day of that month is used.

The example for this item is shown with the ones above: calendar-Jalali.salam

AddYearsJalali

func AddYearsJalali(d: JalaliDate, n: int): JalaliDate
Adds n years to a Jalali date; a leap day missing from the target year moves to the end of the month.

The example for this item is shown with the ones above: calendar-Jalali.salam

DaysBetweenJalali

func DaysBetweenJalali(from: JalaliDate, toDate: JalaliDate): i64
The number of days from from to toDate; negative when the second is earlier.

The example for this item is shown with the ones above: calendar-Jalali.salam

StartOfMonthJalali

func StartOfMonthJalali(d: JalaliDate): JalaliDate
The first day of the month of a Jalali date.

The example for this item is shown with the ones above: calendar-Jalali.salam

EndOfMonthJalali

func EndOfMonthJalali(d: JalaliDate): JalaliDate
The last day of the month of a Jalali date.

The example for this item is shown with the ones above: calendar-Jalali.salam

DaysInJalaliYear

func DaysInJalaliYear(year: int): int
The number of days in a Jalali year: 365 or 366.

The example for this item is shown with the ones above: calendar-Jalali.salam

AddDaysHijri

func AddDaysHijri(d: HijriDate, n: int): HijriDate
Adds n days to a Hijri date; a negative n goes back.
calendar-Hijri.salam
import calendar

func main:
    h := calendar.HijriDate { year = 1445, month = 9, day = 29 }
    println calendar.IsLeapHijri(1445), calendar.IsLeapHijri(1446)
    println calendar.DaysInHijriMonth(1445, 9), calendar.DaysInHijriMonth(1445, 12), calendar.DaysInHijriMonth(1446, 12)
    println calendar.IsValidHijriDate(1445, 9, 30), calendar.IsValidHijriDate(1445, 10, 30)
    println calendar.HijriMonthNameFa(9), calendar.HijriMonthNameAr(9), calendar.HijriMonthNameEn(9)
    println calendar.FormatHijri(calendar.AddDaysHijri(h, 1)), calendar.FormatHijri(calendar.AddWeeksHijri(h, 1))
    println calendar.FormatHijri(calendar.AddMonthsHijri(h, 3)), calendar.FormatHijri(calendar.AddYearsHijri(h, 1))
    println calendar.FormatHijri(calendar.StartOfMonthHijri(h)), calendar.FormatHijri(calendar.EndOfMonthHijri(h))
    muharram := calendar.HijriDate { year = 1446, month = 1, day = 1 }
    println calendar.DaysBetweenHijri(h, muharram), calendar.CompareHijri(h, muharram)
    println calendar.WeekdayNameFa(calendar.WeekdayHijri(h))
end
Outputtrue false 30 30 29 true false رمضان رمضان Ramadan 1445-09-30 1445-10-06 1445-12-29 1446-09-29 1445-09-01 1445-09-30 91 -1 دوشنبه

AddWeeksHijri

func AddWeeksHijri(d: HijriDate, n: int): HijriDate
Adds n weeks to a Hijri date.

The example for this item is shown with the ones above: calendar-Hijri.salam

AddMonthsHijri

func AddMonthsHijri(d: HijriDate, n: int): HijriDate
Adds n months to a Hijri date; when the day does not exist in the target month, the last day of that month is used.

The example for this item is shown with the ones above: calendar-Hijri.salam

AddYearsHijri

func AddYearsHijri(d: HijriDate, n: int): HijriDate
Adds n years to a Hijri date; a leap day missing from the target year moves to the end of the month.

The example for this item is shown with the ones above: calendar-Hijri.salam

DaysBetweenHijri

func DaysBetweenHijri(from: HijriDate, toDate: HijriDate): i64
The number of days from from to toDate; negative when the second is earlier.

The example for this item is shown with the ones above: calendar-Hijri.salam

StartOfMonthHijri

func StartOfMonthHijri(d: HijriDate): HijriDate
The first day of the month of a Hijri date.

The example for this item is shown with the ones above: calendar-Hijri.salam

EndOfMonthHijri

func EndOfMonthHijri(d: HijriDate): HijriDate
The last day of the month of a Hijri date.

The example for this item is shown with the ones above: calendar-Hijri.salam

WeekdayGregorian

func WeekdayGregorian(d: GregorianDate): int
The day of the week of a Gregorian date, counted as Weekday does, with zero Sunday.

The example for this item is shown with the ones above: calendar-Gregorian.salam

WeekdayJalali

func WeekdayJalali(d: JalaliDate): int
The day of the week of a Jalali date, counted as Weekday does, with zero Sunday.

The example for this item is shown with the ones above: calendar-Jalali.salam

WeekdayHijri

func WeekdayHijri(d: HijriDate): int
The day of the week of a Hijri date, counted as Weekday does, with zero Sunday.

The example for this item is shown with the ones above: calendar-Hijri.salam

NextWeekdayOnOrAfter

func NextWeekdayOnOrAfter(d: GregorianDate, weekday: int): GregorianDate
The first day on or after this date whose weekday is weekday; the date itself counts.

The example for this item is shown with the ones above: calendar-Gregorian.salam

HijriToJDN

func HijriToJDN(d: HijriDate): i64
The Julian day number of a Hijri date.

The example for this item is shown with the ones above: calendar-Convert.salam

JDNToHijri

func JDNToHijri(jdn: i64): HijriDate
The Hijri date of a Julian day number.

The example for this item is shown with the ones above: calendar-Convert.salam

IsLeapHijri

func IsLeapHijri(year: int): bool
True when the Hijri year is a leap year, meaning Dhu al-Hijjah has 30 days.

The example for this item is shown with the ones above: calendar-Hijri.salam

DaysInHijriMonth

func DaysInHijriMonth(year: int, month: int): int
The number of days in a Hijri month: 30 for odd months, 29 for even ones, and 30 for Dhu al-Hijjah in a leap year.

The example for this item is shown with the ones above: calendar-Hijri.salam

IsValidHijriDate

func IsValidHijriDate(year: int, month: int, day: int): bool
True when the Hijri date exists.

The example for this item is shown with the ones above: calendar-Hijri.salam

HijriMonthNameAr

func HijriMonthNameAr(month: int): str
The Arabic name of a Hijri month.

The example for this item is shown with the ones above: calendar-Hijri.salam

HijriMonthNameFa

func HijriMonthNameFa(month: int): str
The Persian name of a Hijri month, such as رمضان.

The example for this item is shown with the ones above: calendar-Hijri.salam

HijriMonthNameEn

func HijriMonthNameEn(month: int): str
The Latin name of a Hijri month, such as Ramadan.

The example for this item is shown with the ones above: calendar-Hijri.salam

CompareHijri

func CompareHijri(a: HijriDate, b: HijriDate): int
Compares two Hijri dates: -1, zero or 1.

The example for this item is shown with the ones above: calendar-Hijri.salam

LoadZone

func LoadZone(name: str): Zone
Reads a zone by name, such as America/New_York, from the system tzdata files. On Windows those files are usually absent and ok stays false.

The example for this item is shown with the ones above: calendar-Zone.salam

LocalZone

func LocalZone(): Zone
Reads the machine local zone from the TZ variable or /etc/localtime.

The example for this item is shown with the ones above: calendar-Zone.salam

FreeZone

func FreeZone(z &: Zone)
Frees the memory of a zone.

The example for this item is shown with the ones above: calendar-Zone.salam

ZoneOffsetSeconds

func ZoneOffsetSeconds(z: Zone, epoch: i64): int
The offset of the zone from UTC at that instant, in seconds. Zero when the zone did not load.

The example for this item is shown with the ones above: calendar-Zone.salam

ZoneOffsetMinutes

func ZoneOffsetMinutes(z: Zone, epoch: i64): int
The offset of the zone at that instant, in minutes.

The example for this item is shown with the ones above: calendar-Zone.salam

ZoneIsDST

func ZoneIsDST(z: Zone, epoch: i64): bool
True when the zone is on daylight saving at that instant.

The example for this item is shown with the ones above: calendar-Zone.salam

ZoneAbbrevAt

func ZoneAbbrevAt(z: Zone, epoch: i64): str
The zone abbreviation at that instant, such as EST or EDT.

The example for this item is shown with the ones above: calendar-Zone.salam

TimeZoneAt

func TimeZoneAt(z: Zone, epoch: i64): TimeZone
Returns the offset of the zone at that instant as a fixed TimeZone.

The example for this item is shown with the ones above: calendar-Zone.salam

ZoneAt

func ZoneAt(name: str, epoch: i64): TimeZone
Loads a zone by name and returns its TimeZone at that instant.

The example for this item is shown with the ones above: calendar-Zone.salam

ZonedToEpoch

func ZonedToEpoch(d: GregorianDate, t: ClockTime, z: Zone): i64
Turns a local date and clock time in a zone into an instant, taking daylight saving into account.

The example for this item is shown with the ones above: calendar-Zone.salam