Tempo.Holidays.Locale (Tempo.Holidays v0.1.0)

Resolve a holiday request's target territory.

A request names its target as a positional CLDR territory code (:US, "US") or Localize.LanguageTag.t/0, or through a :territory or :locale option. resolve/2 turns any of these into the territory and the subdivision within it:

:territory — the country ("US").
:subdivision — a subdivision code ("CA"), from a locale's u-sd subdivision (usca) or the :subdivision option, which Tempo.Holidays.Data.subdivision/2 finds at whichever level the data holds it.

A positional code and the :territory option are validated as territories through Localize.validate_territory/1, so :SA is Saudi Arabia — never parsed as the Sanskrit language. A :locale (or a LanguageTag) derives its territory through Localize.Territory.territory_from_locale/1, validated via Localize.validate_locale/1 so untrusted input cannot exhaust the atom table.

Summary

Types

resolved()

Functions

resolve(target, options \\ [])

Resolve a target to {:ok, t:resolved/0}.

Types

resolved()

@type resolved() :: %{territory: String.t() | nil, subdivision: term()}

Functions

resolve(target, options \\ [])

@spec resolve(Localize.LanguageTag.t() | atom() | String.t() | nil, keyword()) ::
  {:ok, resolved()} | {:error, {atom(), term()}}

Resolve a target to {:ok, t:resolved/0}.

Arguments

target is a positional CLDR territory code (atom or string) or a Localize.LanguageTag.t/0; nil when the target is given by option.

Options

:territory — an explicit CLDR territory code (atom or string), validated.
:locale — a BCP 47 locale identifier (atom or string) or a Localize.LanguageTag.t/0, whose territory is derived.
:subdivision — a subdivision code, in place of a locale's own.

Returns

{:ok, t:resolved/0} with the territory upper-cased, and the subdivision as a locale names it or as the option gives it, nil for none.
{:error, {:unknown_territory, code}} for an unrecognised territory, {:error, {:invalid_locale, target}} for a target that is neither, or {:error, {:invalid_option, options}} when options is not a list.

Examples

iex> Tempo.Holidays.Locale.resolve(:AU)
{:ok, %{territory: "AU", subdivision: nil}}

iex> Tempo.Holidays.Locale.resolve(nil, locale: "en-US-u-sd-usca")
{:ok, %{territory: "US", subdivision: "CA"}}

iex> Tempo.Holidays.Locale.resolve(nil, territory: :SA)
{:ok, %{territory: "SA", subdivision: nil}}