# `Tempo.Holidays.Locale`
[🔗](https://github.com/elixir-tempo/tempo_holidays/blob/v0.1.0/lib/tempo/holidays/locale.ex#L1)

Resolve a holiday request's target territory.

A request names its target as a positional CLDR territory code (`:US`, `"US"`)
or `t: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.

# `resolved`

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

# `resolve`

```elixir
@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
  `t: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
  `t: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}}

---

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