# `Calendrical.Time`

Locale-aware time parsing.

Parsing is implemented by Localize: `parse/2` delegates to
`Localize.Time.parse/2`.

When the caller doesn't know in advance whether the input is a
date, time, datetime, or range, use `Calendrical.parse/2`.

# `parse`

```elixir
@spec parse(String.t(), Keyword.t()) ::
  {:ok, Time.t() | map()} | {:error, Exception.t()}
```

Parses a locale-formatted time string. Delegates to `Localize.Time.parse/2`.

Tries, in order: bare ISO-8601 (`HH:MM[:SS[.frac]]`), then
the locale's CLDR short/medium/long/full time patterns.
Locale patterns encode the locale's hour cycle (12-hour for
`en`, `ar`; 24-hour for `de`, `fr`, `ja`) so the same input
may parse to different times under different locales — by
design.

Implements the parts of TR35 §Parsing Dates Times and
§Parsing Day Periods that apply to time-only input.

### Arguments

* `input` is the raw user input string.

* `options` is a keyword list of options.

### Options

* `:locale` — the locale to interpret the string under.
  Defaults to `Localize.get_locale/0`.

* `:as` — `:struct` (default) returns a `t:Time.t/0`.
  `:map` returns a bare field map containing only what the
  input actually supplied (`%{hour: 11}` for `"11 am"`,
  `%{hour: 11, minute: 30, time_zone: "America/Los_Angeles"}` for
  `"11:30 PST"`). `:minute` and `:second` default to `0`
  only in `:struct` mode; in `:map` mode they are omitted
  unless captured. Microsecond is included only when the
  input carried fractional precision. A fixed offset
  (`"2:30 PM GMT+5"`) adds the `t:DateTime.t/0` zone fields
  (`:time_zone`, `:utc_offset`, `:std_offset` and
  `:zone_abbr`); a named zone, whose offset depends on a
  date, is given in `:time_zone` as the zone the name stands
  for, as ICU reads it: `"PST"` is `"America/Los_Angeles"`.

### Returns

* `{:ok, Time.t()}` on success when `as: :struct` (the
  default).

* `{:ok, map()}` on success when `as: :map`. The map
  always has `:hour`; `:minute`, `:second`, `:microsecond`,
  and `:time_zone` appear only when the input supplied
  them.

* `{:error, Localize.TimeParseError.t()}` when no pattern
  matched.

* `{:error, Localize.InvalidValueError.t()}` when `input` is not a string or an option is malformed.

### Examples

    iex> Calendrical.Time.parse("14:30:00", locale: :en)
    {:ok, ~T[14:30:00]}

    iex> Calendrical.Time.parse("2:30 PM", locale: :en)
    {:ok, ~T[14:30:00]}

    iex> Calendrical.Time.parse("14:30", locale: :de)
    {:ok, ~T[14:30:00]}

    iex> Calendrical.Time.parse("11 am", locale: :en, as: :map)
    {:ok, %{hour: 11}}

    iex> Calendrical.Time.parse("11:30", locale: :en, as: :map)
    {:ok, %{hour: 11, minute: 30}}

---

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