Calendrical.Time (Calendrical v0.9.1)

Copy Markdown

Time parsing helpers built on Localize's CLDR data.

See Calendrical.Time.Parser for the parsing engine.

When the caller doesn't know in advance whether the input is a date, time, datetime, or range, use Calendrical.parse/2 — it dispatches to the appropriate sub-parser.

Summary

Functions

parse(input, options \\ [])

Parses a locale-formatted time string.

Functions

parse(input, options \\ [])

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

Parses a locale-formatted time string.

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: "PST"} 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.

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, Calendrical.TimeParseError.t()} when no pattern matched.

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