Calendrical.Time.Parser (Calendrical v0.5.0)

Locale-aware parser for user-typed time strings.

Public entry point: Calendrical.Time.parse/2. Mirrors the structure of Calendrical.Date.Parser — try bare ISO-8601 first, then the locale's CLDR :short / :medium / :long / :full time patterns.

Implements the parts of TR35 §Parsing Dates Times and §Parsing Day Periods that matter for time-only input:

Numeric hour tokens h (1-12), H (0-23), K (0-11), k (1-24) — relaxed to 1-2 digits regardless of pattern count, matching the ICU lenient mode behaviour.
Minute m/mm and second s/ss — relaxed similarly.
Fractional seconds S — variable-precision; we capture 1-9 digits and store as microseconds.
Day-period tokens a (AM/PM) and b (AM/PM + noon / midnight) — case-insensitive match against the locale's day_periods data plus the universal ASCII forms (am/pm/a.m./p.m./AM/PM).
Locale's CLDR lenient-scope-date data drives separator equivalences for :, fractional separator, and surrounding whitespace.

Time-zone tokens (z, Z, v, V, x, X, O) are captured permissively but not currently resolved to an IANA zone. See Calendrical.DateTime.Parser for the datetime case where timezone resolution actually matters.

Summary

Functions

parse(input, options \\ [])

Parses input as a locale-formatted time string.

parse_with_zone(input, options \\ [])

Same as parse/2 but also returns the captured time-zone string (or nil when the pattern carried no zone). The Calendrical.DateTime.Parser uses this to feed Calendrical.TimeZone.resolve/3 for DateTime building.

Functions

parse(input, options \\ [])

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

Parses input as a locale-formatted time string.

See Calendrical.Time.parse/2 for the public contract.

parse_with_zone(input, options \\ [])

@spec parse_with_zone(String.t(), Keyword.t()) ::
  {:ok, Time.t(), String.t() | nil} | {:error, Exception.t()}