Calendrical.Indian (Calendrical v0.3.0)

Copy Markdown

Implementation of the Indian National (Saka) calendar.

The Indian National Calendar is the official civil calendar of India, adopted in 1957 by the Indian Calendar Reform Committee. It is a solar calendar with twelve months whose lengths are derived from the proleptic Gregorian calendar but use historical Indian month names. Year numbering follows the Saka era:

saka_year = gregorian_year - 78

So Saka 1 corresponds to Gregorian 79 CE and 1 Chaitra 1947 Saka = 22 March 2025 CE.

Month structure

#NameDays (ordinary)Days (leap)
1Chaitra3031
2Vaisakha3131
3Jyaistha3131
4Asadha3131
5Sravana3131
6Bhadra3131
7Asvina3030
8Kartika3030
9Agrahayana3030
10Pausa3030
11Magha3030
12Phalguna3030

Total year length is 365 days (366 in leap years). The year is a leap year exactly when the corresponding Gregorian year (saka_year + 78) is a Gregorian leap year. In a Gregorian leap year, the first day of the Saka year (1 Chaitra) falls on 21 March; in an ordinary Gregorian year it falls on 22 March.

Days are assumed to begin at midnight rather than at sunrise.

Reference

  • Indian Calendar Reform Committee, Report of the Calendar Reform Committee, Government of India (1955).
  • Dershowitz & Reingold, Calendrical Calculations (4th ed.), Chapter 11, "The Modern Hindu Calendars".
  • CLDR :indian calendar type.

Summary

Types

day()
month()
year()

Functions

calendar_base()

Identifies whether this calendar is month or week based.

calendar_year(year, month, day)

Returns the calendar year as displayed on rendered calendars.

cldr_calendar_type()

Defines the CLDR calendar type for this calendar.

cyclic_year(year, month, day)

Returns the cyclic year as displayed on rendered calendars.

date_from_iso_days(iso_days)

Returns a Saka {year, month, day} for the given ISO day number.

date_to_iso_days(year, month, day)

Returns the number of ISO days for the given Saka year, month, and day.

day_of_era(year, month, day)

Calculates the day and era from the given year, month, and day.

day_of_year(year, month, day)

Calculates the day of the year from the given year, month, and day.

days_in_month(month)

Returns how many days there are in the given month.

days_in_month(year, month)

Returns the number of days in the given Saka year and month.

days_in_week()

Returns the number days in a a week.

days_in_year(year)

Returns the number of days in the given Saka year (365 or 366).

epoch()
epoch_day_of_week()
extended_year(year, month, day)

Returns the extended year as displayed on rendered calendars.

first_day_of_week()
gregorian_offset()

Returns the offset (in years) between the Saka era and the proleptic Gregorian calendar. saka_year + gregorian_offset() yields the corresponding Gregorian year.

gregorian_year(saka_year)

Returns the Gregorian year corresponding to the given Saka year.

iso_week_of_year(year, month, day)

Calculates the ISO week of the year from the given year, month, and day.

last_day_of_week()
leap_year?(year)

Returns whether the given Saka year is a leap year. The leap year rule is the proleptic Gregorian rule applied to the corresponding Gregorian year.

month(year, month)

Returns a Date.Range.t/0 representing a given month of a year.

month_of_year(year, month, day)

Returns the month of the year from the given year, month, and day.

months_in_leap_year()

Returns the number of months in a leap year.

months_in_ordinary_year()

Returns the number of months in a normal year.

months_in_year(year)

Returns the number of months in a given year.

naive_datetime_from_iso_days(arg)

Converts the t:Calendar.iso_days format to the datetime format specified by this calendar.

naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)

Returns the t:Calendar.iso_days format of the specified date.

periods_in_year(year)

Returns the number of periods in a given year. A period corresponds to a month in month-based calendars and a week in week-based calendars.

plus(year, month, day, date_part, increment, options \\ [])

Adds an increment number of date_parts to a year-month-day.

quarter(year, quarter)

Returns a Date.Range.t/0 representing a given quarter of a year.

quarter_of_year(year, month, day)

Returns the quarter of the year from the given year, month, and day.

related_gregorian_year(year, month, day)

Returns the related gregorain year as displayed on rendered calendars.

saka_year(gregorian_year)

Returns the Saka year corresponding to the given Gregorian year.

valid_date?(year, month, day)

Determines if the given year, month, and day form a valid Saka date.

week(year, week)

Returns a Date.Range.t/0 representing a given week of a year.

week_of_month(year, month, day)

Calculates the week of the year from the given year, month, and day.

week_of_year(year, month, day)

Calculates the week of the year from the given year, month, and day.

weeks_in_year(year)

Returns the number of weeks in a given year.

year(year)

Returns a Date.Range.t/0 representing a given year.

year_of_era(year)

Calculates the year and era from the given year.

year_of_era(year, month, day)

Calculates the year and era from the given date.

Types

day()

@type day() :: 1..31

month()

@type month() :: 1..12

year()

@type year() :: integer()

Functions

calendar_base()

Identifies whether this calendar is month or week based.

calendar_year(year, month, day)

@spec calendar_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the calendar year as displayed on rendered calendars.

cldr_calendar_type()

Defines the CLDR calendar type for this calendar.

This type is used in support of Calendrical. localize/3.

cyclic_year(year, month, day)

@spec cyclic_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the cyclic year as displayed on rendered calendars.

date_from_iso_days(iso_days)

@spec date_from_iso_days(integer()) :: {year(), month(), day()}

Returns a Saka {year, month, day} for the given ISO day number.

date_to_iso_days(year, month, day)

@spec date_to_iso_days(year(), month(), day()) :: integer()

Returns the number of ISO days for the given Saka year, month, and day.

day_of_era(year, month, day)

@spec day_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {day :: Calendar.day(), era :: Calendar.era()}

Calculates the day and era from the given year, month, and day.

By default we consider on two eras: before the epoch and on-or-after the epoch.

day_of_year(year, month, day)

@spec day_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.day()

Calculates the day of the year from the given year, month, and day.

days_in_month(month)

@spec days_in_month(Calendar.month()) ::
  Calendar.month()
  | {:ambiguous, Range.t() | [pos_integer()]}
  | {:error, :undefined}

Returns how many days there are in the given month.

Must be implemented in derived calendars because we cannot know what the calendar format is.

days_in_month(year, month)

@spec days_in_month(Calendar.year(), Calendar.month()) :: Calendar.month()
@spec days_in_month(year(), month()) :: 30..31

Returns the number of days in the given Saka year and month.

days_in_week()

Returns the number days in a a week.

days_in_year(year)

Returns the number of days in the given Saka year (365 or 366).

epoch()

epoch_day_of_week()

extended_year(year, month, day)

@spec extended_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.year()

Returns the extended year as displayed on rendered calendars.

first_day_of_week()

gregorian_offset()

@spec gregorian_offset() :: 78

Returns the offset (in years) between the Saka era and the proleptic Gregorian calendar. saka_year + gregorian_offset() yields the corresponding Gregorian year.

gregorian_year(saka_year)

@spec gregorian_year(year()) :: integer()

Returns the Gregorian year corresponding to the given Saka year.

iso_week_of_year(year, month, day)

@spec iso_week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}

Calculates the ISO week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

last_day_of_week()

leap_year?(year)

@spec leap_year?(year()) :: boolean()

Returns whether the given Saka year is a leap year. The leap year rule is the proleptic Gregorian rule applied to the corresponding Gregorian year.

month(year, month)

Returns a Date.Range.t/0 representing a given month of a year.

month_of_year(year, month, day)

@spec month_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendar.month() | {Calendar.month(), Calendrical.leap_month?()}

Returns the month of the year from the given year, month, and day.

months_in_leap_year()

Returns the number of months in a leap year.

months_in_ordinary_year()

Returns the number of months in a normal year.

months_in_year(year)

Returns the number of months in a given year.

naive_datetime_from_iso_days(arg)

@spec naive_datetime_from_iso_days(Calendar.iso_days()) ::
  {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(),
   Calendar.minute(), Calendar.second(), Calendar.microsecond()}

Converts the t:Calendar.iso_days format to the datetime format specified by this calendar.

naive_datetime_to_iso_days(year, month, day, hour, minute, second, microsecond)

@spec naive_datetime_to_iso_days(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond()
) :: Calendar.iso_days()

Returns the t:Calendar.iso_days format of the specified date.

periods_in_year(year)

Returns the number of periods in a given year. A period corresponds to a month in month-based calendars and a week in week-based calendars.

plus(year, month, day, date_part, increment, options \\ [])

Adds an increment number of date_parts to a year-month-day.

date_part can be :months only.

quarter(year, quarter)

Returns a Date.Range.t/0 representing a given quarter of a year.

quarter_of_year(year, month, day)

@spec quarter_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  Calendrical.quarter()

Returns the quarter of the year from the given year, month, and day.

saka_year(gregorian_year)

@spec saka_year(integer()) :: year()

Returns the Saka year corresponding to the given Gregorian year.

valid_date?(year, month, day)

Determines if the given year, month, and day form a valid Saka date.

week(year, week)

Returns a Date.Range.t/0 representing a given week of a year.

week_of_month(year, month, day)

@spec week_of_month(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {pos_integer(), pos_integer()} | {:error, :not_defined}

Calculates the week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

week_of_year(year, month, day)

@spec week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {:error, :not_defined}

Calculates the week of the year from the given year, month, and day.

By default this function always returns {:error, :not_defined}.

weeks_in_year(year)

Returns the number of weeks in a given year.

year(year)

Returns a Date.Range.t/0 representing a given year.

year_of_era(year)

@spec year_of_era(Calendar.year()) :: {year :: Calendar.year(), era :: Calendar.era()}

Calculates the year and era from the given year.

year_of_era(year, month, day)

@spec year_of_era(Calendar.year(), Calendar.month(), Calendar.day()) ::
  {year :: Calendar.year(), era :: Calendar.era()}

Calculates the year and era from the given date.