# `Calendrical.Preference`

Resolves the preferred Calendrical calendar module for a CLDR locale or an
ISO 3166 territory.

CLDR ships preference rankings that say, for any given territory, which
calendar systems are most appropriate to use. This module turns those
rankings into actual Elixir module names by walking the preference list and
returning the first calendar whose Calendrical implementation is loaded in
the current build.

The two main entry points are:

* `calendar_from_territory/1` — given an ISO 3166 territory code, return the
  preferred calendar module.

* `calendar_from_locale/1` — given a CLDR locale, return the preferred
  calendar module. Honours the `-u-ca-` BCP 47 calendar extension and the
  `-u-fw-` first-day-of-week extension when present.

In every case, if no calendar in the preference list is available, the
module falls back to `Calendrical.Gregorian` (the default calendar), which
is always present.

## Optional calendar packages

Some calendar implementations only ship if their dependencies are loaded —
for example, the lunisolar calendars require `Astro`. The runtime
`Code.ensure_loaded?/1` checks in this module exist precisely so that the
preference resolver gracefully degrades when an optional calendar is not
available in the current build.

# `calendar_for_locale`

> This function is deprecated. Use calendar_from_locale/1.

# `calendar_for_territory`

> This function is deprecated. Use calendar_from_territory/1.

# `calendar_from_locale`

Returns the Calendrical calendar module preferred for the given locale.

Honours the BCP 47 `-u-ca-` calendar extension and the `-u-fw-` first-day-
of-week extension when present in the locale identifier. If no calendar
extension is supplied, falls back to the territory preference list (see
`calendar_from_territory/1`).

### Arguments

* `locale` is a locale identifier atom, string, or a
  `t:Localize.LanguageTag.t/0`. The default is `Localize.get_locale/0`.

### Returns

* `{:ok, calendar_module}` on success.

* `{:error, exception}` if the locale is invalid.

### Examples

    iex> Calendrical.Preference.calendar_from_locale(:"en-GB")
    {:ok, Calendrical.GB}

    iex> Calendrical.Preference.calendar_from_locale("en-GB-u-ca-gregory")
    {:ok, Calendrical.GB}

    iex> Calendrical.Preference.calendar_from_locale(:en)
    {:ok, Calendrical.US}

    iex> Calendrical.Preference.calendar_from_locale("en-u-ca-iso8601")
    {:ok, Calendrical.US}

    iex> Calendrical.Preference.calendar_from_locale("en-u-fw-mon")
    {:ok, Calendrical.US}

    iex> Calendrical.Preference.calendar_from_locale(:"fa-IR")
    {:ok, Calendrical.Persian}

    iex> Calendrical.Preference.calendar_from_locale("fa-IR-u-ca-gregory")
    {:ok, Calendrical.Persian}

# `calendar_from_territory`

Returns the Calendrical calendar module preferred for the given territory.

Walks the CLDR territory preference list and returns the first calendar
whose Calendrical implementation is loaded in the current build. If no
preferred calendar is loaded, falls back to `Calendrical.Gregorian`.

### Arguments

* `territory` is any valid ISO 3166 alpha-2 code as a `t:String.t/0` or an
  upcased `t:atom/0` (e.g. `:US`, `:IR`, `:JP`).

### Returns

* `{:ok, calendar_module}` on success.

* `{:error, exception}` if the territory is unknown.

### Examples

    iex> Calendrical.Preference.calendar_from_territory(:US)
    {:ok, Calendrical.US}

    iex> {:error, %Localize.UnknownTerritoryError{}} =
    ...>   Calendrical.Preference.calendar_from_territory(:YY)

### Notes

The overwhelming majority of territories have `:gregorian` as their first
preferred calendar, so `Calendrical.Gregorian` is returned for most
territories.

Returning any other calendar module requires both that another calendar is
preferred over `:gregorian` for the territory, and that the corresponding
Calendrical implementation is loaded. For example, Iran (`:IR`) prefers the
`:persian` calendar, so `Calendrical.Persian` is returned (the Persian
calendar is built into Calendrical and always available).

# `calendar_from_territory`

---

*Consult [api-reference.md](api-reference.md) for complete listing*