# `Calendrical.TimeZone`

Resolve textual time-zone identifiers captured by the
parser into UTC offsets.

The resolver tries these strategies in order:

1. ISO 8601 offset — `Z`, `±HHMM`, `±HH:MM`, `±HH:MM:SS`.

2. GMT/UTC format — `GMT`, `GMT+10`, `UTC-5:30`.

3. IANA region/city — `Asia/Tokyo`, `America/New_York`.
   Looked up via the host application's installed time-zone
   database (`Tzdata` or `Tz`) — whichever is loaded at
   runtime. If neither is loaded, IANA names are rejected
   (consumer should add `:tzdata` or `:tz` as a dependency
   to support them).

4. Short abbreviation — `PST`, `EST`, `JST`. Resolved via a
   small static table for the most common abbreviations.
   Note that abbreviations are inherently ambiguous (CST
   could be Central or China Standard); the table picks
   the most common North-American/Asian/European reading.

5. CLDR locale name — `Pacific Time`, `Greenwich Mean Time`.
   Looked up via `Localize`'s CLDR `timeZoneNames` data for
   the parsing locale.

When the parser captures a wall-clock instant alongside an
IANA zone, the resolver uses the instant to pick between
standard / daylight offsets (e.g. `2024-07-15 14:00 America/New_York`
→ `EDT (-04:00)`, while `2024-01-15 14:00 America/New_York`
→ `EST (-05:00)`).

# `resolve`

```elixir
@spec resolve(String.t(), NaiveDateTime.t(), Keyword.t()) ::
  {:ok, DateTime.t()} | {:error, atom() | Exception.t()}
```

Resolves `zone_string` against a wall-clock `NaiveDateTime`.

### Arguments

* `zone_string` is the captured zone token (e.g. `"PST"`,
  `"+0530"`, `"Asia/Tokyo"`, `"Pacific Time"`).

* `naive_dt` is the parsed wall-clock instant. Used to
  disambiguate standard vs daylight offsets for IANA
  zones (e.g. `America/New_York` is `-05:00` in January
  and `-04:00` in July).

* `options` is a keyword list of options.

### Options

* `:locale` — locale to use when looking up CLDR-style
  names like `"Pacific Time"`. Defaults to
  `Localize.get_locale/0`.

### Returns

* `{:ok, DateTime.t()}` when the zone resolves.

* `{:error, reason}` when the zone string isn't
  recognizable.

# `tz_database`

```elixir
@spec tz_database() :: module() | nil
```

Returns the configured time-zone database module, or `nil`
when neither `Tzdata` nor `Tz` is loaded.

Consumers that want IANA name resolution should add one of
these to their dependency list. The resolver works without
them but rejects IANA names.

---

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