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

Parses a locale-formatted datetime string.

Tries, in order: bare ISO-8601 (YYYY-MM-DDTHH:MM:SS[Z|±HH:MM]), then the locale's CLDR date-time glue pattern ({1}, {0} in en, {1} {0} in ja, etc.). The glue separator splits the input into date and time portions; each half is parsed by Calendrical.Date.parse/2 and Calendrical.Time.parse/2.

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.

• :calendar — the CLDR calendar key for the date portion. Defaults to :gregorian.

Returns

• {:ok, NaiveDateTime.t()} when no timezone information was present.

• {:ok, DateTime.t()} when the input carried a Z or ±HH:MM offset that ISO-8601 could resolve.

• {:error, Calendrical.DateTimeParseError.t() | …} on failure. Sub-parse errors from Calendrical.Date.parse/2 or Calendrical.Time.parse/2 pass through.

Examples

iex> Calendrical.DateTime.parse("2026-05-16T14:30:00", locale: :en)
{:ok, ~N[2026-05-16 14:30:00]}

iex> Calendrical.DateTime.parse("May 16, 2026, 2:30 PM", locale: :en)
{:ok, ~N[2026-05-16 14:30:00]}

iex> Calendrical.DateTime.parse("16.05.2026, 14:30", locale: :de)
{:ok, ~N[2026-05-16 14:30:00]}