Calendrical.Preference (Calendrical v0.3.0)

Copy Markdown

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.

Summary

Functions

calendar_for_locale(locale) deprecated

See Calendrical.Preference.calendar_from_locale/1.

calendar_for_territory(territory) deprecated

See Calendrical.Preference.calendar_from_territory/1.

calendar_from_locale(locale \\ Localize.get_locale())

Returns the Calendrical calendar module preferred for the given locale.

calendar_from_territory(territory)

Returns the Calendrical calendar module preferred for the given territory.

calendar_from_territory(territory, calendar)

Functions

calendar_for_locale(locale)

This function is deprecated. Use calendar_from_locale/1.

See Calendrical.Preference.calendar_from_locale/1.

calendar_for_territory(territory)

This function is deprecated. Use calendar_from_territory/1.

See Calendrical.Preference.calendar_from_territory/1.

calendar_from_locale(locale \\ Localize.get_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

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(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 String.t/0 or an upcased 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(territory, calendar)