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.Islamic.UmmAlQura)
iex> {year, month, day, 12, 30, 0, {0, 0}} =
...>   Calendrical.Islamic.UmmAlQura.add(date.year, date.month, date.day, 12, 30, 0, {0, 0}, :month, 1)
iex> {year, month, day} == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.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.Islamic.UmmAlQura.calendar_from_cldr_calendar_type(:gregorian)
{:ok, Calendrical.Gregorian}

iex> {:error, %Localize.UnknownCalendarError{}} =
...>   Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {_year, _month, written_day} = Calendrical.Islamic.UmmAlQura.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.cardinal_month(1) == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {written_year, _month, _day} = Calendrical.Islamic.UmmAlQura.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.cldr_calendar_type() == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Islamic.UmmAlQura, date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> cldr_month = Calendrical.Islamic.UmmAlQura.cldr_month(date.year, date.month)
iex> Calendrical.Islamic.UmmAlQura.written_month_from_cldr_month(date.year, cldr_month) ==
...>   Calendrical.Islamic.UmmAlQura.numeric_month(date.year, date.month, date.day)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> cyclic_year = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.cyclic_year(nil, 1, 1)

@spec date_at(DateTime.t(), Keyword.t()) :: {:ok, Date.t()} | {:error, Exception.t()}

Returns the Umm al-Qura date in effect at a given instant, under a chosen day-start convention.

The Islamic day traditionally begins at sunset, so after sunset the Umm al-Qura date is already the following day. This function maps an absolute instant to the Hijri date, choosing the day boundary with the :day_start option. All boundaries are evaluated at Mecca — where the Umm al-Qura calendar is defined — so the result is the official Hijri date for that instant regardless of the observer's own time zone.

For the plain civil-day mapping (the calendar's default), convert a date directly with Date.convert/2 instead.

Arguments

• datetime is a DateTime.t/0 — an absolute instant. Its own time zone is used only to fix the instant; the day boundary is always taken at Mecca.

Options

• :day_start selects the moment the Umm al-Qura day begins:

  • :midnight (the default) — the day begins at 00:00 Mecca time, i.e. the ordinary civil-day mapping.

  • :evening — the day begins at 18:00 Mecca time, the fixed-clock proxy for sunset used by many implementations.

  • :sunset — the day begins at true sunset (Maghrib) at Mecca, computed astronomically via Astro. This is upper-limb sunset, which differs by a minute or two from the centre-of-disk sunset that Calendrical.Islamic.UmmAlQura.Astronomical uses to start each month.

Returns

• {:ok, date} — an Umm al-Qura Date.t/0.

• {:error, %Calendrical.InvalidOptionValueError{}} for an invalid :day_start or :nightfall_angle.

• {:error, %Calendrical.UnsupportedDateRangeError{}} for a date outside the range the calendar or the installed JPL ephemeris covers.

• {:error, %Calendrical.NoDuskError{}} where the sun does not set, or nightfall does not occur, at the location on that day.

Examples

# Morning at Mecca: every convention agrees.
iex> Calendrical.Islamic.UmmAlQura.date_at(~U[2025-03-01 06:00:00Z])
{:ok, ~D[1446-09-01 Calendrical.Islamic.UmmAlQura]}

# After sunset the evening convention has rolled to the next Hijri day.
iex> Calendrical.Islamic.UmmAlQura.date_at(~U[2025-03-01 16:00:00Z], day_start: :evening)
{:ok, ~D[1446-09-02 Calendrical.Islamic.UmmAlQura]}

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.Islamic.UmmAlQura)
iex> {year, month, day} = Calendrical.Islamic.UmmAlQura.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.date_from_cardinal_date(year, month, day) == {date.year, date.month, date.day}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> day_of_year = Calendrical.Islamic.UmmAlQura.day_of_year(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.date_from_day_of_year(date.year, day_of_year) == date
true

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

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

Returns the Umm al-Qura {year, month, day} for the given ISO day number, by the civil calendar outside the published tables.

Arguments

• iso_days is the number of days since the ISO epoch.

Returns

• A {year, month, day} tuple.

Examples

iex> iso_days = Date.to_gregorian_days(~D[2025-03-01])
iex> Calendrical.Islamic.UmmAlQura.date_from_iso_days(iso_days)
{1446, 9, 1}

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.Islamic.UmmAlQura)
iex> {week_year, week, day} = Calendrical.Islamic.UmmAlQura.week_date_from_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.date_from_week_date(week_year, week, day) == date
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {year, month, day} = Calendrical.Islamic.UmmAlQura.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.date_from_written_date(date.year, 0, 1)
{:error, :invalid_date}

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

Returns the number of ISO days for the given Umm al-Qura year, month, and day, by the civil calendar outside the published tables.

Arguments

• year is the Hijri year.

• month is the Hijri month.

• day is the day of the month.

Returns

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

Examples

iex> Calendrical.Islamic.UmmAlQura.date_to_iso_days(1446, 9, 1) ==
...>   Date.to_gregorian_days(~D[2025-03-01])
true

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.Islamic.UmmAlQura)
iex> date in Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.day_numbers(date.year, date.month) ==
...>   [1..Calendrical.Islamic.UmmAlQura.days_in_month(date.year, date.month)//1]
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {day_of_era, era} = Calendrical.Islamic.UmmAlQura.day_of_era(date.year, date.month, date.day)
iex> {_year_of_era, year_era} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.day_of_week(date.year, date.month, date.day, :monday)
{6, 1, 7}

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> first_day = Calendrical.Islamic.UmmAlQura.year(date.year).first
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {fewest, most} = Calendrical.Islamic.UmmAlQura.days_in_month_bounds(date.month)
iex> case Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.days_in_month(99)

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

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

Returns the number of days in the given Hijri year and month. Months are 29 or 30 days as determined by the published Umm al-Qura tables, or by the civil calendar outside them.

Arguments

• year is the Hijri year.

• month is the Hijri month, from 1 to 12.

Returns

• The number of days in the month, 29 or 30, 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> Calendrical.Islamic.UmmAlQura.days_in_month(1446, 9)
29

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.Islamic.UmmAlQura)
iex> {fewest, most} = Calendrical.Islamic.UmmAlQura.days_in_month_bounds(date.month)
iex> Calendrical.Islamic.UmmAlQura.days_in_month(date.year, date.month) in fewest..most
true

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

Returns the number of days in a week.

Returns

• 7.

Examples

iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.days_in_year(date.year) == Enum.count(Calendrical.Islamic.UmmAlQura.year(date.year))
true

iex> {:error, %Calendrical.MissingFieldsError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> from = {date.year, date.month, date.day}
iex> Calendrical.Islamic.UmmAlQura.diff(from, {date.year + 1, date.month, date.day}, :years)
1

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> later = Date.add(date, 10)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.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.Islamic.UmmAlQura.era_calendar_type() == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.extended_year(date.year, date.month, date.day) == date.year
true

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

@spec first_day_of_month(year(), month()) :: {:ok, Date.t()} | {:error, Exception.t()}

Returns the Gregorian Calendar.date/0 of the first day of the given Hijri month according to the official Umm al-Qura tables.

Arguments

• hijri_year is the Hijri year.

• hijri_month is the Hijri month, from 1 to 12.

Returns

• {:ok, date} where date is the Gregorian Date.t/0 of the first day of the month.

• {:error, %Calendrical.IslamicYearOutOfRangeError{}} if the requested month falls outside the embedded data range, where the calendar's months are the civil calendar's.

• {:error, %Calendrical.InvalidMonthError{}} for a month that is not 1 to 12.

Examples

iex> Calendrical.Islamic.UmmAlQura.first_day_of_month(1446, 9)
{:ok, ~D[2025-03-01]}

iex> {:error, %Calendrical.IslamicYearOutOfRangeError{}} =
...>   Calendrical.Islamic.UmmAlQura.first_day_of_month(1700, 1)

iex> {:error, %Calendrical.InvalidMonthError{year: 1446, month: 13}} =
...>   Calendrical.Islamic.UmmAlQura.first_day_of_month(1446, 13)

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

Returns

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

Examples

iex> Calendrical.Islamic.UmmAlQura.info().calendar
Calendrical.Islamic.UmmAlQura

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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> leap_month = Calendrical.Islamic.UmmAlQura.leap_month(date.year)
iex> is_nil(leap_month) or leap_month in 1..Calendrical.Islamic.UmmAlQura.months_in_year(date.year)
true

Returns whether the given Hijri year is a leap year (355 days).

Arguments

• year is the Hijri year.

Returns

• true if the year has 355 days, otherwise false.

Examples

iex> Calendrical.Islamic.UmmAlQura.leap_year?(1447)
true

iex> Calendrical.Islamic.UmmAlQura.leap_year?(1446)
false

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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.lunar_month_of_year(date.year, date.month) ==
...>   Calendrical.Islamic.UmmAlQura.traditional_month(date.year, date.month)
true

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

@spec max_year() :: 1600

Returns the last Hijri year covered by the embedded Umm al-Qura tables: KACST's to 1500 AH, then ICU's.

Returns

• The last Hijri year of the tables, as an integer.

Examples

iex> Calendrical.Islamic.UmmAlQura.max_year()
1600

@spec min_year() :: 1

Returns the first Hijri year covered by the embedded Umm al-Qura tables.

Returns

• The first Hijri year of the tables, as an integer.

Examples

iex> Calendrical.Islamic.UmmAlQura.min_year()
1

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.Islamic.UmmAlQura)
iex> date in Calendrical.Islamic.UmmAlQura.month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> traditional_month = Calendrical.Islamic.UmmAlQura.traditional_month(date.year, date.month)
iex> Calendrical.Islamic.UmmAlQura.month_from_traditional(date.year, traditional_month) == date.month
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.month_numbers(date.year) == [1..Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.month_of_year(date.year, date.month, date.day) == Calendrical.Islamic.UmmAlQura.cldr_month(date.year, date.month)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.months_in_leap_year() >= Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.months_in_ordinary_year() <= Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.months_in_year() do
...>   months when is_integer(months) -> months == Calendrical.Islamic.UmmAlQura.months_in_leap_year()
...>   {:ambiguous, fewest..most//1} -> {fewest, most} == Calendrical.Islamic.UmmAlQura.info().months_in_year
...>   {:error, %Calendrical.NotDefinedError{}} -> is_list(Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.months_in_year_bounds()
iex> fewest <= Calendrical.Islamic.UmmAlQura.months_in_ordinary_year() and
...>   most >= Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {year, month, day, 12, 0, 0, {0, 6}} =
...>   Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> cldr_month = Calendrical.Islamic.UmmAlQura.cldr_month(date.year, date.month)
iex> Calendrical.Islamic.UmmAlQura.named_month(date.year, cldr_month) |> Enum.any?(&(date in &1))
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {_year, written_month, _day} = Calendrical.Islamic.UmmAlQura.written_date(date.year, date.month, date.day)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> traditional_month = Calendrical.Islamic.UmmAlQura.traditional_month(date.year, date.month)
iex> Calendrical.Islamic.UmmAlQura.ordinal_month_from_traditional(date.year, traditional_month) == {:ok, date.month}
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidMonthError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.parse_date(Date.to_string(date)) == {:ok, {date.year, date.month, date.day}}
true

iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura.parsing_calendar() == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> in_effect = Calendrical.Info.in_effect(Calendrical.Islamic.UmmAlQura, date.year, date.month, date.day)
iex> in_effect in Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.periods_in_year(date.year) == Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.quadrimester(date.year, 1).first == Calendrical.Islamic.UmmAlQura.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> quarter = Calendrical.Islamic.UmmAlQura.quarter_of_year(date.year, date.month, date.day)
iex> date in Calendrical.Islamic.UmmAlQura.quarter(date.year, quarter)
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.quarter_of_year(date.year, date.month, date.day) in 1..4
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {:ok, first_day} = Date.convert(Calendrical.Islamic.UmmAlQura.year(date.year).first, Calendrical.Gregorian)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.semester(date.year, 1).first == Calendrical.Islamic.UmmAlQura.year(date.year).first
true

iex> {:ok, date} = Date.convert(~D[2024-06-01], Calendrical.Islamic.UmmAlQura)
iex> {:error, %Calendrical.InvalidDateError{}} = Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> Calendrical.Islamic.UmmAlQura.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.Islamic.UmmAlQura)
iex> {year, month, day} = Calendrical.Islamic.UmmAlQura.shift_date(date.year, date.month, date.day, Duration.new!(day: 7))
iex> Date.new!(year, month, day, Calendrical.Islamic.UmmAlQura) == 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.Islamic.UmmAlQura)
iex> next_day = Date.add(date, 1)
iex> Calendrical.Islamic.UmmAlQura.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