# `Calendrical.Islamic.UmmAlQura` Implementation of the Saudi Arabian Umm al-Qura calendar. The Umm al-Qura (أم القرى, "Mother of Towns" — a name for Mecca) calendar is the official Hijri calendar of the Kingdom of Saudi Arabia and the basis for date calculations published by the King Abdulaziz City for Science and Technology (KACST). It differs from the purely tabular Hijri calendars (`Calendrical.Islamic.Civil` and `Calendrical.Islamic.Tbla`) in that the start of each month is determined by an astronomical observation rule applied at Mecca rather than by a fixed arithmetic cycle. Individual months may therefore deviate from the tabular value by up to a day. This module embeds the official KACST Umm al-Qura tables (sourced from R.H. van Gent's Utrecht University dataset, cross-referenced against the KACST publications) at compile time. Every conversion between an Umm al-Qura date and a Gregorian date is therefore an O(log n) lookup with no floating-point arithmetic at runtime. ## Coverage The embedded data covers approximately **1356 AH through ~1500 AH** (March 1937 CE through ~2076 CE). Dates outside this range raise `Calendrical.IslamicYearOutOfRangeError` from `date_to_iso_days/3` and `date_from_iso_days/1`. Days are assumed to begin at midnight rather than at sunset. ## Reference - R.H. van Gent, "The Umm al-Qura Calendar of Saudi Arabia", - KACST published Umm al-Qura tables. # `day` ```elixir @type day() :: 1..30 ``` # `month` ```elixir @type month() :: 1..12 ``` # `year` ```elixir @type year() :: pos_integer() ``` # `calendar_base` Identifies whether this calendar is month or week based. # `calendar_year` ```elixir @spec calendar_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year() ``` Returns the calendar year as displayed on rendered calendars. # `cldr_calendar_type` Defines the CLDR calendar type for this calendar. This type is used in support of `Calendrical. localize/3`. # `cyclic_year` ```elixir @spec cyclic_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year() ``` Returns the cyclic year as displayed on rendered calendars. # `date_from_iso_days` ```elixir @spec date_from_iso_days(integer()) :: {year(), month(), day()} ``` Returns the Umm al-Qura `{year, month, day}` for the given ISO day number. Raises `Calendrical.IslamicYearOutOfRangeError` if `iso_days` is outside the embedded reference range. # `date_to_iso_days` ```elixir @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`. Raises `Calendrical.IslamicYearOutOfRangeError` if the date is outside the embedded reference range. # `day_of_era` ```elixir @spec day_of_era(Calendar.year(), Calendar.month(), Calendar.day()) :: {day :: Calendar.day(), era :: Calendar.era()} ``` Calculates the day and era from the given `year`, `month`, and `day`. By default we consider on two eras: before the epoch and on-or-after the epoch. # `day_of_year` ```elixir @spec day_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.day() ``` Calculates the day of the year from the given `year`, `month`, and `day`. # `days_in_month` ```elixir @spec days_in_month(Calendar.month()) :: Calendar.month() | {:ambiguous, Range.t() | [pos_integer()]} | {:error, :undefined} ``` Returns how many days there are in the given month. Must be implemented in derived calendars because we cannot know what the calendar format is. # `days_in_month` ```elixir @spec days_in_month(Calendar.year(), Calendar.month()) :: Calendar.month() @spec days_in_month(year(), month()) :: 29..30 ``` 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. # `days_in_week` Returns the number days in a a week. # `days_in_year` Returns the number of days in the given Hijri `year` (354 or 355). # `epoch` # `epoch_day_of_week` # `extended_year` ```elixir @spec extended_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year() ``` Returns the extended year as displayed on rendered calendars. # `first_day_of_month` ```elixir @spec first_day_of_month(year(), month()) :: {:ok, Date.t()} | {:error, Exception.t()} ``` Returns the Gregorian `t:Calendar.date/0` of the first day of the given Hijri month according to the official Umm al-Qura tables. Returns `{:error, %Calendrical.IslamicYearOutOfRangeError{}}` if the requested month falls outside the embedded data range. # `first_day_of_week` # `iso_week_of_year` ```elixir @spec iso_week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: {:error, :not_defined} ``` Calculates the ISO week of the year from the given `year`, `month`, and `day`. By default this function always returns `{:error, :not_defined}`. # `last_day_of_week` # `leap_year?` Returns whether the given Hijri `year` is a leap year (355 days). # `max_year` ```elixir @spec max_year() :: pos_integer() ``` Returns the last Hijri year covered by the embedded Umm al-Qura reference data. # `min_year` ```elixir @spec min_year() :: pos_integer() ``` Returns the first Hijri year covered by the embedded Umm al-Qura reference data. # `month` Returns a `t:Date.Range.t/0` representing a given month of a year. # `month_of_year` ```elixir @spec month_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.month() | {Calendar.month(), Calendrical.leap_month?()} ``` Returns the month of the year from the given `year`, `month`, and `day`. # `months_in_leap_year` Returns the number of months in a leap year. # `months_in_ordinary_year` Returns the number of months in a normal year. # `months_in_year` Returns the number of months in a given `year`. # `naive_datetime_from_iso_days` ```elixir @spec naive_datetime_from_iso_days(Calendar.iso_days()) :: {Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond()} ``` Converts the `t:Calendar.iso_days` format to the datetime format specified by this calendar. # `naive_datetime_to_iso_days` ```elixir @spec naive_datetime_to_iso_days( Calendar.year(), Calendar.month(), Calendar.day(), Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond() ) :: Calendar.iso_days() ``` Returns the `t:Calendar.iso_days` format of the specified date. # `periods_in_year` Returns the number of periods in a given `year`. A period corresponds to a month in month-based calendars and a week in week-based calendars. # `plus` Adds an `increment` number of `date_part`s to a `year-month-day`. `date_part` can be `:months` only. # `quarter` Returns a `t:Date.Range.t/0` representing a given quarter of a year. # `quarter_of_year` ```elixir @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`. # `related_gregorian_year` ```elixir @spec related_gregorian_year(Calendar.year(), Calendar.month(), Calendar.day()) :: Calendar.year() ``` Returns the related gregorain year as displayed on rendered calendars. # `valid_date?` Determines if the given Umm al-Qura date is valid. A date is valid if its `year` falls within the embedded reference range, its `month` is in `1..12`, and its `day` is between 1 and the number of days in that month according to the published tables. # `week` Returns a `t:Date.Range.t/0` representing a given week of a year. # `week_of_month` ```elixir @spec week_of_month(Calendar.year(), Calendar.month(), Calendar.day()) :: {pos_integer(), pos_integer()} | {:error, :not_defined} ``` Calculates the week of the year from the given `year`, `month`, and `day`. By default this function always returns `{:error, :not_defined}`. # `week_of_year` ```elixir @spec week_of_year(Calendar.year(), Calendar.month(), Calendar.day()) :: {:error, :not_defined} ``` Calculates the week of the year from the given `year`, `month`, and `day`. By default this function always returns `{:error, :not_defined}`. # `weeks_in_year` Returns the number of weeks in a given `year`. # `year` Returns a `t:Date.Range.t/0` representing a given year. # `year_of_era` ```elixir @spec year_of_era(Calendar.year()) :: {year :: Calendar.year(), era :: Calendar.era()} ``` Calculates the year and era from the given `year`. # `year_of_era` ```elixir @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`. --- *Consult [api-reference.md](api-reference.md) for complete listing*