# Calendrical v2.2.0 - Table of Contents

> Localized month- and week-based calendars and calendar functions
based upon CLDR data via Localize.

## Pages

- [Calendrical](readme.md)
- [License](license.md)
- [Unicode License](license-unicode.md)
- [Changelog](changelog.md)

- Guides
  - [Making a calendar](calendar_behaviour.md)
  - [Available Calendars](calendar_summary.md)
  - [Composite calendars](composite_calendars.md)
  - [Migrating from ex_cldr_calendars](migration.md)
  - [Parsing dates, times, datetimes, and intervals](parsing.md)
  - [Supervision](supervision.md)

## Modules

- [Calendrical](Calendrical.md): Calendar functions for calendars compatible with
Elixir's `Calendar` behaviour.
- [Calendrical.ISO](Calendrical.ISO.md): The proleptic Gregorian calendar with ISO 8601 week rules.

- Gregorian Month-based Calendars
  - [Calendrical.Buddhist](Calendrical.Buddhist.md): Implementation of the Thai Buddhist (Buddhist Era) calendar.
  - [Calendrical.Gregorian](Calendrical.Gregorian.md): Implements the proleptic Gregorian calendar.
  - [Calendrical.Indian](Calendrical.Indian.md): Implementation of the Indian National (Saka) calendar.
  - [Calendrical.Japanese](Calendrical.Japanese.md): Implements the Japanese calendar that is calendrically
the same as the proleptic Gregorian calendar but has a
different era structure.
  - [Calendrical.Roc](Calendrical.Roc.md): Implementation of the Republic of China (Minguo) calendar.

- Gregorian Week-based Calendars
  - [Calendrical.ISOWeek](Calendrical.ISOWeek.md): Implements the ISO Week calendar.
  - [Calendrical.NRF](Calendrical.NRF.md): Implements the US National Retail Federation
(NRF) calendar.

- Julian Calendars
  - [Calendrical.Julian](Calendrical.Julian.md): Implements the proleptic Julian calendar.
  - [Calendrical.Julian.Dec25](Calendrical.Julian.Dec25.md): Proleptic Julian calendar whose year begins on 25 December (the
*Nativity style* / *Christmas style*, used in parts of medieval
Europe and the early Holy Roman Empire).
  - [Calendrical.Julian.Jan1](Calendrical.Julian.Jan1.md): Proleptic Julian calendar whose year begins on 1 January
(the modern "Circumcision style", widely adopted after 1582).
  - [Calendrical.Julian.March1](Calendrical.Julian.March1.md): Proleptic Julian calendar whose year begins on 1 March (the
*Venetian style*, *more veneto*, used by the Republic of Venice).
  - [Calendrical.Julian.March25](Calendrical.Julian.March25.md): Proleptic Julian calendar whose year begins on 25 March (the
*Annunciation style* / *Lady Day*, used in England before 1752
and in Florence during the Middle Ages).
  - [Calendrical.Julian.Sept1](Calendrical.Julian.Sept1.md): Proleptic Julian calendar whose year begins on 1 September (the
*Byzantine* year, used by the Byzantine Empire and in the Eastern
Orthodox liturgical year).

- Lunisolar Calendars
  - [Calendrical.Chinese](Calendrical.Chinese.md): Implementation of the Chinese lunisolar calendar.
  - [Calendrical.Hebrew](Calendrical.Hebrew.md): Implementation of the Hebrew (Jewish) calendar.
  - [Calendrical.Korean](Calendrical.Korean.md): Implementation of the Korean lunisolar calendar.
  - [Calendrical.LunarJapanese](Calendrical.LunarJapanese.md): Implementation of the Japanese lunisolar calendar.
  - [Calendrical.Lunisolar](Calendrical.Lunisolar.md): Shared base implementation for Calendrical's lunisolar calendars.
  - [Calendrical.Vietnamese](Calendrical.Vietnamese.md): Implementation of the Vietnamese lunisolar calendar (âm lịch).

- Ethiopic Calendars
  - [Calendrical.Ethiopic](Calendrical.Ethiopic.md): Implementation of the Ethiopic calendar.
  - [Calendrical.Ethiopic.AmeteAlem](Calendrical.Ethiopic.AmeteAlem.md): Implementation of the Ethiopic calendar with the *Amete Alem* (Era
of the World, *Anno Mundi*) year numbering.

- Islamic Calendars
  - [Calendrical.Islamic.Civil](Calendrical.Islamic.Civil.md): Implementation of the tabular Islamic (Hijri) civil calendar.
  - [Calendrical.Islamic.Observational](Calendrical.Islamic.Observational.md): Implementation of the *observational* (sighting-based) Islamic
calendar.
  - [Calendrical.Islamic.Rgsa](Calendrical.Islamic.Rgsa.md): Implementation of the *Saudi Arabian sighting-based* Islamic
calendar (CLDR `:islamic_rgsa`).
  - [Calendrical.Islamic.Tbla](Calendrical.Islamic.Tbla.md): Implementation of the tabular Islamic (Hijri) calendar based on the
*astronomical* epoch.
  - [Calendrical.Islamic.UmmAlQura](Calendrical.Islamic.UmmAlQura.md): Implementation of the Saudi Arabian Umm al-Qura calendar.
  - [Calendrical.Islamic.UmmAlQura.Astronomical](Calendrical.Islamic.UmmAlQura.Astronomical.md): Implements the Umm al-Qura calendar for determining the first day of each
Hijri month using the astronomical rules documented by R. H. van Gent.
  - [Calendrical.Islamic.UmmAlQura.ReferenceData](Calendrical.Islamic.UmmAlQura.ReferenceData.md): Umm al-Qura month starts computed by R.H. van Gent (Utrecht University)
from the published Umm al-Qura rules, used as the reference data for
`Calendrical.Islamic.UmmAlQura.Astronomical`.

- Ecclesiastical Calendars
  - [Calendrical.Ecclesiastical](Calendrical.Ecclesiastical.md): Computes the dates of Christian ecclesiastical events for a given
Gregorian year.

- Other Calendars
  - [Calendrical.Composite](Calendrical.Composite.md): A composite calendar uses one base calendar before a specified
transition date and a different calendar after, optionally chaining
multiple transitions to model a sequence of historical calendar
reforms.
  - [Calendrical.Coptic](Calendrical.Coptic.md): Implementation of the Coptic calendar.
  - [Calendrical.Persian](Calendrical.Persian.md): The present Iranian calendar was legally adopted on 31
March 1925, under the early Pahlavi dynasty. The law
said that the first day of the year should be the
first day of spring in "the true solar year", "as it
has been" ever so. It also fixes the number of days
in each month, which previously varied by year with
the sidereal zodiac.

- Reform Calendars
  - [Calendrical.Reform](Calendrical.Reform.md): Per-territory Julian-to-Gregorian reform calendars.
  - [Calendrical.Reform.England](Calendrical.Reform.England.md): A composite calendar that tracks the historical calendar in use in England.
  - [Calendrical.Reform.Japan](Calendrical.Reform.Japan.md): A composite calendar that tracks the historical calendar in use in Japan.
  - [Calendrical.Reform.Sweden](Calendrical.Reform.Sweden.md): A composite calendar that tracks the historical calendar in use in Sweden.
  - [Calendrical.Reform.Sweden.Transitional](Calendrical.Reform.Sweden.Transitional.md): The transitional "Swedish calendar" in use between 1700 and 1712.

- Fiscal-year Calendars
  - [Calendrical.FiscalYear](Calendrical.FiscalYear.md): Pre-built fiscal-year calendars for ISO 3166 territories.

- Makers
  - [Calendrical.Calendar](Calendrical.Calendar.md): Makes a hand-written calendar: one whose spine, `date_to_iso_days/3`
and `date_from_iso_days/1`, the author writes, with `leap_year?/1`,
`months_in_year/1` and `days_in_month/2`, and `leap_month/1` where the
calendar has a leap month. Every other answer, from the day of the week
to the ranges of a quarter, is derived from those and from the facts
the options state, as `c:Calendrical.info/0` carries them.
  - [Calendrical.Calendar.Lunisolar](Calendrical.Calendar.Lunisolar.md): Makes a lunisolar calendar reckoned from the sky: a year of twelve or
thirteen lunar months that begins at the second new moon after the
winter solstice, with the leap month placed by the solar terms, as the
Chinese, Korean, Vietnamese and traditional Japanese calendars are.
  - [Calendrical.Calendar.Shifted](Calendrical.Calendar.Shifted.md): Makes a calendar whose year begins elsewhere in a base calendar's year:
a fiscal year beginning in July, a year counted from Lady Day as the
Old Style did, or any year begun on a day of a calendar of months.
  - [Calendrical.Calendar.Weeks](Calendrical.Calendar.Weeks.md): Makes a calendar of whole weeks: a year of 52 or 53 weeks that begins
or ends on a weekday near a day of the Gregorian year, cut into twelve
months of four or five weeks by a pattern, as retail and other fiscal
calendars count them and as the ISO week year does.

- Derived API
  - [Calendrical.Era](Calendrical.Era.md): Era arithmetic for CLDR calendars.
  - [Calendrical.Info](Calendrical.Info.md): The static facts about a calendar, as data.
  - [Calendrical.Month](Calendrical.Month.md): The months of any calendar, computed once for every calendar from its
kernel: how a month is named and numbered, which months a year has and
which days a month has, and the lengths a month can have.
  - [Calendrical.Period](Calendrical.Period.md): The periods of a calendar's year, computed for every calendar from its
kernel: the days of a year and of a month, the quarters, quadrimesters
and semesters, the day of the year and the days a year has.
  - [Calendrical.Shift](Calendrical.Shift.md): Date arithmetic for a calendar whose months are counted by their
position in the year: the implementation of `c:Calendrical.shift/6`
and `c:Calendrical.diff/3` that `use Calendrical.Calendar` supplies,
computed from the calendar's kernel.
  - [Calendrical.Week](Calendrical.Week.md): The weeks of any calendar, computed once for every calendar from its
kernel.

- Behaviours
  - [Calendrical.Formatter](Calendrical.Formatter.md): Calendar formatter behaviour.

- Runtime
  - [Calendrical.Supervisor](Calendrical.Supervisor.md): The `:calendrical` runtime supervisor.

- Parsing
  - [Calendrical.Date](Calendrical.Date.md): Locale-aware date parsing for Calendrical's calendars.
  - [Calendrical.DateTime](Calendrical.DateTime.md): Locale-aware datetime parsing for Calendrical's calendars.
  - [Calendrical.Time](Calendrical.Time.md): Locale-aware time parsing.
  - [Calendrical.TimeZone](Calendrical.TimeZone.md): Resolves a time zone as a locale writes it, with the date and time
written with it, to a `t:DateTime.t/0`.

- Formatting
  - [Calendrical.Format](Calendrical.Format.md): Renders Calendrical calendars as years, months, weeks, and days using a
pluggable formatter.

- Intervals
  - [Calendrical.Interval](Calendrical.Interval.md): Constructs and compares date intervals for any Calendrical calendar.

- K-day Calculations
  - [Calendrical.Kday](Calendrical.Kday.md): Provide K-Day functions for Dates, DateTimes and NaiveDateTimes.

- Preference
  - [Calendrical.Preference](Calendrical.Preference.md): Resolves the preferred Calendrical calendar module for a CLDR locale or an
ISO 3166 territory.

- Exceptions
  - [Calendrical.AstronomyError](Calendrical.AstronomyError.md): Exception returned when an astronomical calculation behind a calendar
cannot be made for a reason other than the dates it covers, which
`Calendrical.UnsupportedDateRangeError` describes.
  - [Calendrical.Formatter.InvalidDateError](Calendrical.Formatter.InvalidDateError.md): Exception raised when a value supplied to a calendar formatter
is not a recognised date.
  - [Calendrical.Formatter.InvalidOptionError](Calendrical.Formatter.InvalidOptionError.md): Exception raised when an unknown option, or an option with an
invalid value, is supplied to a calendar formatter.
  - [Calendrical.Formatter.UnknownFormatterError](Calendrical.Formatter.UnknownFormatterError.md): Exception raised when a calendar formatter module cannot be
resolved.
  - [Calendrical.IncompatibleCalendarError](Calendrical.IncompatibleCalendarError.md): Exception raised when an operation is attempted between two
dates or datetimes that use incompatible calendars.
  - [Calendrical.IncompatibleTimeZoneError](Calendrical.IncompatibleTimeZoneError.md): Exception raised when two datetimes that should be in the same
time zone are not.
  - [Calendrical.InvalidCalendarModuleError](Calendrical.InvalidCalendarModuleError.md): Exception raised when a module is referenced as a calendar but
does not implement the `Calendar` (and `Calendrical`) behaviour.
  - [Calendrical.InvalidCompositeError](Calendrical.InvalidCompositeError.md): Exception returned, or raised by `use Calendrical.Composite`, for a
configuration a composite calendar cannot keep.
  - [Calendrical.InvalidDateError](Calendrical.InvalidDateError.md): Exception returned when a value is not a date of a calendar: a day the
month does not have, a month the year does not have, a week the year
does not have, or a field that is not an integer.
  - [Calendrical.InvalidDateOrderError](Calendrical.InvalidDateOrderError.md): Exception raised when two dates or times are not ordered from
earlier to later as required by the function being called.
  - [Calendrical.InvalidMonthError](Calendrical.InvalidMonthError.md): Exception returned when a month is one a calendar, or a year of it,
does not have.
  - [Calendrical.InvalidOptionValueError](Calendrical.InvalidOptionValueError.md): Exception returned, or raised by a calendar maker, when an option is given
a value it cannot take: an unknown `:day_start`, a `:nightfall_angle` that
is not a number, a `:location` that is not a place, or a calendar maker's
option in a form it does not take.
  - [Calendrical.InvalidPartError](Calendrical.InvalidPartError.md): Exception raised when an unknown date part is supplied to a
localization function.
  - [Calendrical.InvalidSolarTermError](Calendrical.InvalidSolarTermError.md): Exception returned when a solar term is asked for by a number that names
none: the twenty-four solar terms are numbered `1` to `24`.
  - [Calendrical.InvalidStyleError](Calendrical.InvalidStyleError.md): Exception raised when an unknown date style width is supplied
to a localization function.
  - [Calendrical.InvalidTypeError](Calendrical.InvalidTypeError.md): Exception raised when an unknown date format type is supplied
to a localization function.
  - [Calendrical.IslamicYearOutOfRangeError](Calendrical.IslamicYearOutOfRangeError.md): Exception raised when an operation on the Umm al-Qura Islamic calendar
references a Hijri year that lies outside the embedded reference data.
  - [Calendrical.MissingFieldsError](Calendrical.MissingFieldsError.md): Exception raised when a date or datetime does not have all
the fields required by the function being called.
  - [Calendrical.NoDuskError](Calendrical.NoDuskError.md): Exception returned when a day that begins at dusk has no dusk: at a
place and date where the sun does not set, or does not go as far below
the horizon as nightfall asks, as in a polar summer.
  - [Calendrical.NotDefinedError](Calendrical.NotDefinedError.md): Exception returned when a calendar does not define what was asked of
it: weeks in a calendar without them, a cycle of years in a calendar
whose years do not repeat, or one count of days for a month whose days
change from year to year.
  - [Calendrical.RemovedOptionError](Calendrical.RemovedOptionError.md): Exception returned when an option Calendrical 2.0 removed is given, such
as the parse functions' `:return_calendar`, so that a caller written for
1.x is told rather than silently given another result. The CHANGELOG and
the migration guide say what replaces each.
  - [Calendrical.UnknownFiscalYearError](Calendrical.UnknownFiscalYearError.md): Exception returned by `Calendrical.FiscalYear.calendar_for/1` for a
territory whose fiscal year it does not know.
  - [Calendrical.UnknownOptionError](Calendrical.UnknownOptionError.md): Exception raised by a calendar maker (`use Calendrical.Calendar` and the
others), and returned by `Calendrical.new/3` and
`Calendrical.Composite.new/2`, for options the maker does not read.
  - [Calendrical.UnknownReformError](Calendrical.UnknownReformError.md): Exception returned by `Calendrical.Reform` for a territory whose change
from the Julian to the Gregorian calendar it does not know, or a value
that is no territory.
  - [Calendrical.UnsupportedDateRangeError](Calendrical.UnsupportedDateRangeError.md): Exception raised when a date lies outside the range a calendar
can compute.

## Mix Tasks

- [mix calendrical.umm_al_qura.verify](Mix.Tasks.Calendrical.UmmAlQura.Verify.md): Verifies the Umm al-Qura tables embedded in Calendrical and, optionally,
compares them with KACST's official data or another reference.