# `Localize.DateTime.Parser`
[🔗](https://github.com/elixir-localize/localize/blob/v1.4.0/lib/localize/datetime/parser.ex#L1)

Parses a locale-formatted string as whichever temporal value it turns
out to be — a date, a time, a datetime, or a date range.

`Localize.Date.parse/2`, `Localize.Time.parse/2`,
`Localize.DateTime.parse/2` and `Localize.Interval.parse/2` each parse
one shape and expect the caller to know which. `parse/2` here is for
the case where the shape is not known up front: a single text field
that may carry any of `"2026-05-16"`, `"14:30"`, `"May 16, 2026 2:30
PM"` or `"May 5 – May 10, 2026"`. The caller pattern-matches on the
returned struct to discover what was parsed.

# `parse`

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

Parses a locale-formatted string as a date, time, datetime, or date
range — whichever matches.

### Arguments

* `input` is the string to parse.

* `options` is a keyword list of options.

### Options

* `:locale` is any locale returned by `Localize.all_locale_ids/0`.
  The default is `Localize.get_locale/0`.

* Remaining options are passed to whichever sub-parser matches.

### Returns

* `{:ok, value}` where `value` is a `t:Date.t/0`, `t:Time.t/0`,
  `t:NaiveDateTime.t/0`, `t:DateTime.t/0` or `t:Date.Range.t/0`.

* `{:error, exception}`, a `t:Localize.DateTimeParseError.t/0` whose
  `:attempts` records what each sub-parser reported, or a
  `t:Localize.InvalidValueError.t/0` if `input` is not a string or an
  option is malformed.

### Examples

    iex> Localize.DateTime.Parser.parse("March 22, 2026", locale: :en)
    {:ok, ~D[2026-03-22]}

    iex> Localize.DateTime.Parser.parse("3:45 PM", locale: :en)
    {:ok, ~T[15:45:00]}

---

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