Identifies whether this calendar is month or week based.

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

Returns the calendar year as displayed on rendered calendars.

Defines the CLDR calendar type for this calendar.

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

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

Returns the cyclic year as displayed on rendered calendars.

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

Returns a {year, month, day} tuple representing the Persian calendar date for the given count of ISO days.

Arguments

• iso_days is an integer count of days since the proleptic ISO epoch.

Returns

• A three-tuple {year, month, day} in the Persian calendar.

Examples

iex> Calendrical.Persian.date_from_iso_days(739_335)
{1403, 1, 6}

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

Returns the number of days since the ISO calendar epoch for a given Persian year, month, and day.

Arguments

• year is any Persian year as an integer.

• month is a Persian month in the range 1..12.

• day is a Persian day-of-month in the range 1..31.

Returns

• An integer count of days since the proleptic ISO epoch.

Examples

iex> Calendrical.Persian.date_to_iso_days(1404, 1, 1)
739696

@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.

@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.

@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.

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

Returns how many days there are in the given year and month.

Returns the number days in a a week.

Returns the number days in a given year.

The year is the number of years since the epoch.

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

Returns the extended year as displayed on rendered calendars.

@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}.

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

Returns whether the given Persian year is a leap year.

Since this calendar is observational we calculate the start of successive years and then calculate the difference in days to determine whether it is a leap year.

Arguments

• year is any Persian year as an integer.

Returns

• true if the year contains 366 days; otherwise false.

Examples

iex> Calendrical.Persian.leap_year?(1403)
true

iex> Calendrical.Persian.leap_year?(1404)
false

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

@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.

Returns the number of months in a leap year.

Returns the number of months in a normal year.

Returns the number of months in a given year.

@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.

@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.

@spec new_year_gregorian(Calendar.year()) :: {:ok, Date.t()}

Returns the Gregorian Date of the Persian new year that falls in the given Gregorian year.

The Persian new year (Nowruz) is the day on which the March equinox occurs in Tehran local time.

Arguments

• year is the Gregorian year in which the desired Persian new year falls.

Returns

• {:ok, date} where date is a Date.t/0 in Calendar.ISO.

Examples

iex> Calendrical.Persian.new_year_gregorian(2025)
{:ok, ~D[2025-03-21]}

@spec new_year_on_or_before(integer()) :: integer()

Returns the count of ISO days of the most recent Persian new year on or before iso_days.

Arguments

• iso_days is an integer count of days since the proleptic ISO epoch.

Returns

• An integer count of days since the proleptic ISO epoch corresponding to the most recent Persian new year on or before the supplied date.

Examples

iex> Calendrical.Persian.new_year_on_or_before(739_400)
739330

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.

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

date_part can be :months only.

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

@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.

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

Returns the related gregorain year as displayed on rendered calendars.

Determines if the date given is valid according to this calendar.

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

@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}.

@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}.

Returns the number of weeks in a given year.

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

@spec year_end_gregorian(Calendar.year()) :: {:ok, Date.t()}

Returns the Gregorian Date of the last day of the Persian year that begins in the given Gregorian year.

Arguments

• year is the Gregorian year in which the Persian year starts.

Returns

• {:ok, date} where date is a Date.t/0 in Calendar.ISO, one day before the next Persian new year.

Examples

iex> Calendrical.Persian.year_end_gregorian(2025)
{:ok, ~D[2026-03-20]}

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

Calculates the year and era from the given year.

@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.