Adds whole years, quarters or months to the fields of a naive datetime, keeping its time of day: the add/9 callback CalendarInterval steps an interval of a year or a month with. The date moves as shift/6 moves it, clamping the day into a shorter month.

Arguments

• year, month and day are the date's fields in this calendar.

• hour, minute, second and microsecond are the time of day, returned unchanged.

• precision is :year, :quarter or :month.

• step is the number of years, quarters or months to add, which may be negative.

Returns

• {year, month, day, hour, minute, second, microsecond}.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {year, month, day, 12, 30, 0, {0, 0}} =
...>   Calendrical.Gregorian.add(date.year, date.month, date.day, 12, 30, 0, {0, 0}, :month, 1)
iex> {year, month, day} == Calendrical.Gregorian.shift(date.year, date.month, date.day, :months, 1, [])
true

Returns what this calendar's year is built of, :month or :week, as its info/0 states.

Returns

• :week for a calendar whose year is built of weeks.

• :month otherwise.

Examples

iex> Calendrical.Gregorian.calendar_base() in [:month, :week]
true

Returns the calendar module whose CLDR calendar type is the one given, whichever calendar is asked (Calendrical.calendar_from_cldr_calendar_type/1).

Arguments

• calendar_type is a CLDR calendar type as an atom or a string.

Returns

• {:ok, calendar_module}, or

• {:error, exception} for a calendar type no calendar module has.

Examples

iex> Calendrical.Gregorian.calendar_from_cldr_calendar_type(:gregorian)
{:ok, Calendrical.Gregorian}

iex> {:error, %Localize.UnknownCalendarError{}} =
...>   Calendrical.Gregorian.calendar_from_cldr_calendar_type(:not_a_calendar)

Returns the day a date is written with: the day of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The day of the date's written_date/3, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {_year, _month, written_day} = Calendrical.Gregorian.written_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.cardinal_day(date.year, date.month, date.day) == written_day
true

Returns the CLDR month a month of the year names without a year (Calendrical.Month.cldr_month/2).

Arguments

• month is a month of this calendar.

Returns

• The CLDR month the month is named in the year that holds 1 January 2000, the month itself in the Hebrew calendar, whose names depend on the year, and the month itself where the reference year has no such month.

Examples

iex> {:ok, date} = Date.convert(~D[2000-01-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.cardinal_month(1) == Calendrical.Gregorian.cldr_month(date.year, 1)
true

Returns the year a date is written with: the year of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The year of the date's written_date/3, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {written_year, _month, _day} = Calendrical.Gregorian.written_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.cardinal_year(date.year, date.month, date.day) == written_year
true

Returns the CLDR calendar type whose data names this calendar's months, days and quarters, as its info/0 states.

Returns

• A CLDR calendar type such as :gregorian or :hebrew.

Examples

iex> Calendrical.Gregorian.cldr_calendar_type() == Calendrical.Gregorian.info().cldr_calendar_type
true

Returns the CLDR calendar type whose data names a date's months and days: the member in effect on the date in a composite calendar, and this calendar's own otherwise (Calendrical.Info.cldr_calendar_type/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• A CLDR calendar type.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Gregorian, date.year, date.month, date.day)
iex> Calendrical.Gregorian.cldr_calendar_type(date.year, date.month, date.day) == in_effect.cldr_calendar_type()
true

Returns the CLDR month of a month of a year (Calendrical.Month.cldr_month/3).

Arguments

• year and month are a month of this calendar.

Returns

• A CLDR month number, or {month, :leap} where the month's name has a leap form, or

• {:error, exception} for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> cldr_month = Calendrical.Gregorian.cldr_month(date.year, date.month)
iex> Calendrical.Gregorian.written_month_from_cldr_month(date.year, cldr_month) ==
...>   Calendrical.Gregorian.numeric_month(date.year, date.month, date.day)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.cldr_month(date.year, 99)

Returns the cyclic year of a date (Calendrical.Era.cyclic_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The date's place in the sexagenary cycle, 1 to 60, in an East Asian calendar, and its year in a calendar whose years run in no such cycle, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> cyclic_year = Calendrical.Gregorian.cyclic_year(date.year, date.month, date.day)
iex> cyclic_year in 1..60 or cyclic_year == date.year
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Gregorian.cyclic_year(nil, 1, 1)

Returns the date of this calendar that written figures name (date_from_written_date/3), as fields.

Arguments

• year, month and day are the figures a date is written with, as written_date/3 returns them.

Returns

• {year, month, day}, the date of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where the figures name no date.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {year, month, day} = Calendrical.Gregorian.written_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.date_from_cardinal_date(year, month, day) == {date.year, date.month, date.day}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.date_from_cardinal_date(date.year, 0, 1)

Returns the date of a day of a year, counted from the year's first day.

Arguments

• year is a year of this calendar.

• day_of_year is the day of the year, counted from 1.

Returns

• A Date.t/0 of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} for a day the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> day_of_year = Calendrical.Gregorian.day_of_year(date.year, date.month, date.day)
iex> Calendrical.Gregorian.date_from_day_of_year(date.year, day_of_year) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.date_from_day_of_year(date.year, 1000)

Returns the date of a day of a week of a week-year (Calendrical.Week.date_from_week_date/4).

Arguments

• week_year is a week-year of this calendar.

• week is a week of the week-year.

• day is the day of the week, numbered from 1 for the day the calendar's weeks begin on.

Returns

• A Date.t/0 of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where the week has no such day.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {week_year, week, day} = Calendrical.Gregorian.week_date_from_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.date_from_week_date(week_year, week, day) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.date_from_week_date(date.year, 1, 8)

Returns the date of this calendar that written figures name: the inverse of written_date/3, the fields themselves where they are a date.

Arguments

• year, month and day are the figures a date is written with, as written_date/3 returns them.

Returns

• {:ok, {year, month, day}}, the date of this calendar, or

• {:error, :invalid_date} where the figures name no date.

The reason is an atom, not an exception: Localize's date parser reads it, as Calendrical.date_from_written_date/3 sets out.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {year, month, day} = Calendrical.Gregorian.written_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.date_from_written_date(year, month, day) == {:ok, {date.year, date.month, date.day}}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.date_from_written_date(date.year, 0, 1)
{:error, :invalid_date}

Returns the dates of this calendar, earliest first, whose month and day are those given and that fall in a Gregorian year.

Arguments

• gregorian_year is the Gregorian year to search within.

• month and day are a month and a day of this calendar.

Returns

• A list of zero, one or two Date.t/0 of this calendar, earliest first, since this calendar's years and the Gregorian years drift.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> date in Calendrical.Gregorian.dates_in_gregorian_year(2024, date.month, date.day)
true

Returns the days a month of a year has, as runs of their numbers (Calendrical.Month.day_numbers/3).

Arguments

• year and month are a month of this calendar.

Returns

• A list of ranges: one from 1 in every month of every calendar but a composite, whose month a change of calendar falls in has the days that are left, and [] for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.day_numbers(date.year, date.month) ==
...>   [1..Calendrical.Gregorian.days_in_month(date.year, date.month)//1]
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.day_numbers(date.year, 99)
[]

Returns the day of era and era of a date (Calendrical.Era.day_of_era/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• {day_of_era, era}, where the day of the era counts from the era's first day, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {day_of_era, era} = Calendrical.Gregorian.day_of_era(date.year, date.month, date.day)
iex> {_year_of_era, year_era} = Calendrical.Gregorian.year_of_era(date.year, date.month, date.day)
iex> day_of_era >= 1 and era == year_era
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.day_of_era(date.year, date.month, 0)

Returns the day of the week of a date (Calendrical.Week.day_of_week/5).

Arguments

• year, month and day are a date of this calendar.

• starting_on is :default for the day this calendar's weeks begin on, or the name of a weekday, :monday to :sunday.

Returns

• {day_of_week, 1, 7}, the day numbered from the day the week begins on, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

# 1 June 2024 is a Saturday
iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.day_of_week(date.year, date.month, date.day, :monday)
{6, 1, 7}

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.day_of_week(date.year, date.month, 0, :monday)

Returns the day of the year of a date (Calendrical.Period.day_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The day of the year, counted from 1 for its first day, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing field.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> first_day = Calendrical.Gregorian.year(date.year).first
iex> Calendrical.Gregorian.day_of_year(date.year, date.month, date.day) == Date.diff(date, first_day) + 1
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.day_of_year(date.year, date.month, 0)

Returns the number of days in a month without a year (Calendrical.Month.days_in_month/2).

Arguments

• month is a month of this calendar.

Returns

• The number of days where the month has as many in every year, or

• {:ambiguous, lengths} where its length depends on the year, the lengths a range or, where they are not consecutive, a list, or

• {:error, %Calendrical.NotDefinedError{}} for a month the calendar has in no year, or

• {:error, exception}, a Calendrical.MissingFieldsError, where the month is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {fewest, most} = Calendrical.Gregorian.days_in_month_bounds(date.month)
iex> case Calendrical.Gregorian.days_in_month(date.month) do
...>   days when is_integer(days) -> fewest == days and most == days
...>   {:ambiguous, lengths} -> Enum.min(lengths) == fewest and Enum.max(lengths) == most
...> end
true

iex> {:error, %Calendrical.NotDefinedError{}} = Calendrical.Gregorian.days_in_month(99)

@spec days_in_month(Calendar.year(), Calendar.month()) ::
  Calendar.day() | {:error, Exception.t()}

@spec days_in_month(Calendar.year(), Calendar.month()) ::
  Calendar.day() | {:error, Exception.t()}

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

Arguments

• year is a year of this calendar.

• month is a month of the year.

Returns

• The number of days in the month, or

• {:error, %Calendrical.InvalidMonthError{}} for a month the year does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the month is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.days_in_month(date.year, date.month) >= date.day
true

Returns the fewest and the most days a month has in any year (Calendrical.Month.days_in_month_bounds/2).

Arguments

• month is a month of this calendar.

Returns

• {fewest, most}, or

• {:error, exception} for a month the calendar has in no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {fewest, most} = Calendrical.Gregorian.days_in_month_bounds(date.month)
iex> Calendrical.Gregorian.days_in_month(date.year, date.month) in fewest..most
true

iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.days_in_month_bounds(99)

Returns the number of days in a week.

Returns

• 7.

Examples

iex> Calendrical.Gregorian.days_in_week()
7

Returns the number of days in a year (Calendrical.Period.days_in_year/2).

Arguments

• year is a year of this calendar.

Returns

• The number of days, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.days_in_year(date.year) == Enum.count(Calendrical.Gregorian.year(date.year))
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Gregorian.days_in_year(nil)

Returns the number of whole units between two dates, counted positionally.

Arguments

• from and to are dates of this calendar as {year, month, day} tuples.

• date_part is one of :years, :quarters, :months, :weeks or :days.

Returns

• The largest number of date_parts that can be added to from without passing to, negative where to is before from, or

• {:error, %Calendrical.InvalidDateError{}} for a from or to the calendar does not have, {:error, %Calendrical.MissingFieldsError{}} for one missing a field, or {:error, %Calendrical.InvalidPartError{}} for a date_part other than the five.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> from = {date.year, date.month, date.day}
iex> Calendrical.Gregorian.diff(from, {date.year + 1, date.month, date.day}, :years)
1

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> later = Date.add(date, 10)
iex> Calendrical.Gregorian.diff({later.year, later.month, later.day}, {date.year, date.month, date.day}, :days)
-10

Returns the epoch of this calendar: the ISO day number of its first day.

Returns

• The epoch as an integer number of days since the ISO epoch.

Examples

iex> Calendrical.Gregorian.epoch() |> is_integer()
true

Returns the CLDR calendar type that names this calendar's eras, as its info/0 states.

Returns

• A CLDR calendar type such as :gregorian or :japanese.

Examples

iex> Calendrical.Gregorian.era_calendar_type() == Calendrical.Gregorian.info().era_calendar_type
true

Returns the extended year of a date (Calendrical.Era.extended_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The year numbered without a gap at 0, so that in a calendar with no year 0 the year before 1 is 0, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.extended_year(date.year, date.month, date.day) == date.year
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Gregorian.extended_year(nil, 1, 1)

Returns the static facts about this calendar, as Calendrical.Info.t/0.

Returns

• A Calendrical.Info.t/0 describing this calendar.

Examples

iex> Calendrical.Gregorian.info().calendar
Calendrical.Gregorian

Returns the ISO 8601 week-year and week of the day a date names (Calendrical.Week.iso_week_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• {week_year, week} of ISO 8601, or

• {:error, exception} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.iso_week_of_year(date.year, date.month, date.day)
{2024, 22}

Returns the position of a year's leap month, or nil where the year has none.

Arguments

• year is a year of this calendar.

Returns

• The leap month's position in the year, or

• nil where the year has no leap month, as for anything but an integer year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> leap_month = Calendrical.Gregorian.leap_month(date.year)
iex> is_nil(leap_month) or leap_month in 1..Calendrical.Gregorian.months_in_year(date.year)
true

Returns the traditional month at a position in a year (Calendrical.Month.traditional_month/3), or an error for a place the year does not have.

Arguments

• year and month are a month of this calendar.

Returns

• The month's traditional number, or {month, :leap} for a leap month, or

• {:error, %Calendrical.InvalidMonthError{}} for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.lunar_month_of_year(date.year, date.month) ==
...>   Calendrical.Gregorian.traditional_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.lunar_month_of_year(date.year, 99)

Returns the days of a month of a year (Calendrical.Period.month/3).

Arguments

• year and month are a month of this calendar.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a month the year does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing year or month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> date in Calendrical.Gregorian.month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.month(date.year, 99)

Returns the position of a traditional month in a year (Calendrical.Month.month_from_traditional/3).

Arguments

• year is a year of this calendar.

• traditional_month is a month's traditional number, or {month, :leap} for a leap month.

Returns

• The month's position in the year, or

• {:error, exception} where the year has no such month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> traditional_month = Calendrical.Gregorian.traditional_month(date.year, date.month)
iex> Calendrical.Gregorian.month_from_traditional(date.year, traditional_month) == date.month
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.month_from_traditional(date.year, 99)

Returns the months a year has, as runs of their numbers (Calendrical.Month.month_numbers/2).

Arguments

• year is a year of this calendar.

Returns

• A list of ranges: one from 1 in every year of every calendar but a composite, whose year a change of calendar falls in has the months that are left, and [] for a year the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.month_numbers(date.year) == [1..Calendrical.Gregorian.months_in_year(date.year)//1]
true

Returns the CLDR month of a month of a year: the index of its name in this calendar's CLDR data, with {month, :leap} where the name has a leap form (Calendrical.Month.cldr_month/3).

Arguments

• year, month and day are a date of this calendar. The year and the day may be nil: a month's name needs only the month.

Returns

• A CLDR month number, or {month, :leap}, or

• {:error, %Calendrical.InvalidDateError{}} for a day the month does not have, or

• {:error, exception} for a month the year does not have, or a Calendrical.MissingFieldsError where the month is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.month_of_year(date.year, date.month, date.day) == Calendrical.Gregorian.cldr_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.month_of_year(date.year, date.month, 0)

Returns the number of months in a leap year: the most months a year of this calendar has.

Returns

• A positive integer.

Examples

iex> Calendrical.Gregorian.months_in_leap_year() >= Calendrical.Gregorian.months_in_ordinary_year()
true

Returns the number of months in an ordinary year: the fewest months a year of this calendar has.

Returns

• A positive integer.

Examples

iex> Calendrical.Gregorian.months_in_ordinary_year() <= Calendrical.Gregorian.months_in_leap_year()
true

Returns the number of months in a year without a year: the count where every year has as many, {:ambiguous, range} where a leap year has more, and {:error, %Calendrical.NotDefinedError{}} for a composite calendar (Calendrical.Info.months_in_year/1).

Returns

• The number of months where every year has as many, or

• {:ambiguous, fewest..most} where a leap year has more, or

• {:error, %Calendrical.NotDefinedError{}} for a composite calendar, whose bounds months_in_year_bounds/0 gives.

Examples

iex> case Calendrical.Gregorian.months_in_year() do
...>   months when is_integer(months) -> months == Calendrical.Gregorian.months_in_leap_year()
...>   {:ambiguous, fewest..most//1} -> {fewest, most} == Calendrical.Gregorian.info().months_in_year
...>   {:error, %Calendrical.NotDefinedError{}} -> is_list(Calendrical.Gregorian.info().members)
...> end
true

Returns the number of months in a given year.

Arguments

• year is the year in this calendar.

Returns

• The number of months in the year, as a positive integer, or

• {:error, %Calendrical.MissingFieldsError{}} where year is nil, or

• {:error, %Calendrical.InvalidDateError{}} where year is no integer.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.months_in_year(date.year) >= date.month
true

Returns the fewest and the most months a year has (Calendrical.Month.months_in_year_bounds/1).

Returns

• {fewest, most}, which in a composite calendar counts the months left in a year a change of calendar falls in.

Examples

iex> {fewest, most} = Calendrical.Gregorian.months_in_year_bounds()
iex> fewest <= Calendrical.Gregorian.months_in_ordinary_year() and
...>   most >= Calendrical.Gregorian.months_in_leap_year()
true

Converts ISO days and a day fraction to a naive datetime of this calendar, as Calendar.naive_datetime_from_iso_days/1 asks.

Arguments

• iso_days is {days, {parts_in_day, parts_per_day}}, a day and a fraction of it.

Returns

• {year, month, day, hour, minute, second, microsecond} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {year, month, day, 12, 0, 0, {0, 6}} =
...>   Calendrical.Gregorian.naive_datetime_from_iso_days({739403, {43200000000, 86400000000}})
iex> {year, month, day} == {date.year, date.month, date.day}
true

Converts a naive datetime of this calendar to ISO days and a day fraction, as Calendar.naive_datetime_to_iso_days/7 asks.

Arguments

• year, month and day are a date of this calendar.

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

Returns

• {iso_days, {parts_in_day, parts_per_day}}.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.naive_datetime_to_iso_days(date.year, date.month, date.day, 12, 0, 0, {0, 6})
{739403, {43200000000, 86400000000}}

Returns the days of a named month in a year (Calendrical.Month.named_month/3).

Arguments

• year is a year of this calendar.

• named_month is the CLDR month that names the month.

Returns

• A list of Date.Range.t/0, one for each counted month that carries the name, earliest first, and [] where none does.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> cldr_month = Calendrical.Gregorian.cldr_month(date.year, date.month)
iex> Calendrical.Gregorian.named_month(date.year, cldr_month) |> Enum.any?(&(date in &1))
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.named_month(date.year, 99)
[]

Returns the number a date's month is written with in figures: the month of its written_date/3.

Arguments

• year, month and day are a date of this calendar.

Returns

• The month of the date's written_date/3: a month number, or {month, :leap} for a leap month of a lunisolar calendar, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {_year, written_month, _day} = Calendrical.Gregorian.written_date(date.year, date.month, date.day)
iex> Calendrical.Gregorian.numeric_month(date.year, date.month, date.day) == written_month
true

Returns the position in a year of a traditional month (Calendrical.Month.month_from_traditional/3), as {:ok, month}.

Arguments

• year is a year of this calendar.

• traditional_month is a month's traditional number, or {month, :leap} for a leap month.

Returns

• {:ok, month}, the month's position in the year, or

• {:error, %Calendrical.InvalidMonthError{}} for a month or a leap month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> traditional_month = Calendrical.Gregorian.traditional_month(date.year, date.month)
iex> Calendrical.Gregorian.ordinal_month_from_traditional(date.year, traditional_month) == {:ok, date.month}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.ordinal_month_from_traditional(date.year, 99)

Parses a date written in this calendar's own notation.

Arguments

• string is a date written YYYY-MM-DD, with a leading - for a year before 1, or, in a calendar of weeks, YYYY-Www-D.

Returns

• {:ok, {year, month, day}}, or

• {:error, :invalid_format} where the text is not in that form or its fields are not digits, or

• {:error, :invalid_date} where the text names no date of this calendar.

The reason is an atom, not an exception, because Calendar.parse_date/1 requires one: Date.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.parse_date(Date.to_string(date)) == {:ok, {date.year, date.month, date.day}}
true

iex> Calendrical.Gregorian.parse_date("not a date")
{:error, :invalid_format}

Parses a naive datetime written in this calendar's own notation.

Arguments

• string is a date as parse_date/1 reads it, then T or a space and a time of day.

Returns

• {:ok, {year, month, day, hour, minute, second, microsecond}}, or

• {:error, reason}, such as :invalid_format or :invalid_date, where the text is no such datetime.

The reason is an atom, not an exception, because Calendar.parse_naive_datetime/1 requires one: NaiveDateTime.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.parse_naive_datetime(Date.to_string(date) <> "T12:00:00") ==
...>   {:ok, {date.year, date.month, date.day, 12, 0, 0, {0, 0}}}
true

iex> Calendrical.Gregorian.parse_naive_datetime("2024-06-01")
{:error, :invalid_format}

Parses a UTC datetime written in this calendar's own notation.

Arguments

• string is a date as parse_date/1 reads it, then T or a space, a time of day and an offset from UTC, Z or ±HH:MM.

Returns

• {:ok, {year, month, day, hour, minute, second, microsecond}, offset}, the datetime in UTC and the offset in seconds it was written with, or

• {:error, reason}, such as :invalid_format, :invalid_date or :missing_offset, where the text is no such datetime.

The reason is an atom, not an exception, because Calendar.parse_utc_datetime/1 requires one: DateTime.from_iso8601/2 reads it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.parse_utc_datetime(Date.to_string(date) <> "T12:00:00Z") ==
...>   {:ok, {date.year, date.month, date.day, 12, 0, 0, {0, 0}}, 0}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.parse_utc_datetime(Date.to_string(date) <> "T12:00:00")
{:error, :missing_offset}

Returns the calendar a date written for this calendar is parsed in, as its info/0 states.

Returns

• A calendar module.

Examples

iex> Calendrical.Gregorian.parsing_calendar() == Calendrical.Gregorian.info().parsing_calendar
true

Returns the calendars a date written for this calendar may be written in: the members of a composite calendar, and this calendar alone otherwise (Calendrical.Info.parsing_calendars/1).

Returns

• A non-empty list of calendar modules, the members of a composite calendar in the order they take effect.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Gregorian, date.year, date.month, date.day)
iex> in_effect in Calendrical.Gregorian.parsing_calendars()
true

Returns the number of periods in a year: its months.

Arguments

• year is a year of this calendar.

Returns

• The number of months in the year, as months_in_year/1 returns it.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.periods_in_year(date.year) == Calendrical.Gregorian.months_in_year(date.year)
true

Returns the days of a quadrimester of a year (Calendrical.Period.quadrimester/3).

Arguments

• year is a year of this calendar.

• quadrimester is the quadrimester, 1 to 3.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a quadrimester or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the quadrimester is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.quadrimester(date.year, 1).first == Calendrical.Gregorian.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.quadrimester(date.year, 4)

Returns the days of a quarter of a year (Calendrical.Period.quarter/3).

Arguments

• year is a year of this calendar.

• quarter is the quarter, 1 to 4.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a quarter or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the quarter is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> quarter = Calendrical.Gregorian.quarter_of_year(date.year, date.month, date.day)
iex> date in Calendrical.Gregorian.quarter(date.year, quarter)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.quarter(date.year, 5)

Returns the quarter of the year a date falls in (Calendrical.Period.quarter_of_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The quarter, 1 to 4, or

• {:error, %Calendrical.InvalidDateError{}} for a date the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for a missing year or month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.quarter_of_year(date.year, date.month, date.day) in 1..4
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.quarter_of_year(date.year, date.month, 0)

Returns the related Gregorian year of a date (Calendrical.Era.related_gregorian_year/4).

Arguments

• year, month and day are a date of this calendar.

Returns

• The Gregorian year the date's calendar year begins in, or

• {:error, %Calendrical.InvalidDateError{}} for a year the calendar does not have, or

• {:error, exception}, a Calendrical.MissingFieldsError, for no year.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:ok, first_day} = Date.convert(Calendrical.Gregorian.year(date.year).first, Calendrical.Gregorian)
iex> Calendrical.Gregorian.related_gregorian_year(date.year, date.month, date.day) == first_day.year
true

Returns the days of a semester of a year (Calendrical.Period.semester/3).

Arguments

• year is a year of this calendar.

• semester is the semester, 1 or 2.

Returns

• A Date.Range.t/0, or

• {:error, %Calendrical.InvalidDateError{}} for a semester or a year the calendar does not have, or

• {:error, %Calendrical.MissingFieldsError{}} where the year or the semester is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.semester(date.year, 1).first == Calendrical.Gregorian.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Gregorian.semester(date.year, 3)

Returns the date a number of years, quarters, months, weeks or days on from a date of this calendar, by position, with the traditional month kept across years and a day the resulting month lacks clamped to its last day unless clamp: false (Calendrical.Shift.shift/7).

Arguments

• year, month and day are a date of this calendar.

• date_part is one of :years, :quarters, :months, :weeks or :days.

• increment is the number of units, which may be negative.

• options is a keyword list of options.

Options

• :clamp is whether a day the resulting month lacks becomes its last day. The default is true.

Returns

• {year, month, day} of this calendar, or

• {:error, %Calendrical.InvalidDateError{}} where year, month and day are no date of this calendar, or

• {:error, %Calendrical.MissingFieldsError{}} where a field is nil.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.shift(date.year, date.month, date.day, :days, 0)
{date.year, date.month, date.day}

Shifts a date by a duration: its years and months together, as shift/6 adds months, and then its weeks and days.

Arguments

• year, month and day are a date of this calendar.

• duration is a Duration.t/0.

Returns

• {year, month, day} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {year, month, day} = Calendrical.Gregorian.shift_date(date.year, date.month, date.day, Duration.new!(day: 7))
iex> Date.new!(year, month, day, Calendrical.Gregorian) == Date.add(date, 7)
true

Shifts a naive datetime by a duration: its date as shift_date/4 shifts it, and its time as Calendar.ISO does.

Arguments

• year, month and day are a date of this calendar.

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

• duration is a Duration.t/0.

Returns

• {year, month, day, hour, minute, second, microsecond} of this calendar.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> next_day = Date.add(date, 1)
iex> Calendrical.Gregorian.shift_naive_datetime(date.year, date.month, date.day, 23, 0, 0, {0, 0}, Duration.new!(hour: 2)) ==
...>   {next_day.year, next_day.month, next_day.day, 1, 0, 0, {0, 0}}
true

Shifts a time by a duration, as Calendar.ISO does.

Arguments

• hour, minute, second and microsecond are a time of day, the microsecond as {microseconds, precision}.

• duration is a Duration.t/0 of time units.

Returns

• {hour, minute, second, microsecond}, wrapped around midnight.

Examples

iex> Calendrical.Gregorian.shift_time(23, 0, 0, {0, 0}, Duration.new!(hour: 2))
{1, 0, 0, {0, 0}}

Returns the day of a solar term of a Gregorian year, reckoned at the place this calendar's info/0 names, or at the Chinese calendar's meridian, the traditional reference, where it names none.

Arguments

• index is the solar term's number, 1 (lichun, 315° of solar longitude) to 24, every 15° on.

• gregorian_year is a Gregorian year.

Returns

• {:ok, date}, a Date.t/0 in Calendrical.Gregorian, or

• {:error, %Calendrical.InvalidSolarTermError{}} where index is not 1 to 24.

Examples

# Qingming, the fifth solar term
iex> Calendrical.Gregorian.solar_term(5, 2025)
{:ok, ~D[2025-04-04 Calendrical.Gregorian]}

iex> Calendrical.Gregorian.solar_term(25, 2025)
{:error, %Calendrical.InvalidSolarTermError{index: 25}}

Returns the traditional number of the month a year's leap month follows, or nil (Calendrical.Month.traditional_leap_month/2).

Arguments

• year is a year of this calendar.

Returns

• The traditional number of the month the leap month follows, or

• nil where the year has no leap month.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> is_nil(Calendrical.Gregorian.traditional_leap_month(date.year)) ==
...>   is_nil(Calendrical.Gregorian.leap_month(date.year))
true

Returns a month of a year as this calendar names it (Calendrical.Month.traditional_month/3).

Arguments

• year and month are a month of this calendar.

Returns

• The month's traditional number, or {month, :leap} for a leap month, or

• {:error, exception} for a month the year does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.traditional_month(date.year, date.month) ==
...>   Enum.at(Calendrical.Gregorian.traditional_months(date.year), date.month - 1)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Gregorian.traditional_month(date.year, 99)

Returns a year's months in order, named traditionally (Calendrical.Month.traditional_months/2).

Arguments

• year is a year of this calendar.

Returns

• A list of traditional months, the nth naming the year's nth month, with {month, :leap} for a leap month, and [] for a year the calendar does not have.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> length(Calendrical.Gregorian.traditional_months(date.year)) ==
...>   Calendrical.Gregorian.months_in_year(date.year)
true

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

Arguments

• year is a year of this calendar.

• month is a month of the year.

• day is a day of the month.

Returns

• true if the year, month and day are a date of this calendar, otherwise false.

Examples

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Gregorian)
iex> Calendrical.Gregorian.valid_date?(date.year, date.month, date.day)
true
iex> Calendrical.Gregorian.valid_date?(date.year, date.month, 0)
false