@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 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 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}}