# `Localize.Date`
[🔗](https://github.com/elixir-localize/localize/blob/v1.3.0/lib/localize/date.ex#L1)

Provides localized formatting of `Date` structs and date-like maps.

Supports both full dates (`%{year: _, month: _, day: _}`) and partial
dates (any map with one or more of `:year`, `:month`, `:day`). For
partial dates, the format is derived from the available fields.

Formats are defined in CLDR and described in
[TR35](http://unicode.org/reports/tr35/tr35-dates.html).

# `parse`

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

Parses a localized date string.

Parsing lives in the companion [calendrical](https://hex.pm/packages/calendrical)
package, which carries the calendar systems Localize formats for.
`calendrical` depends on Localize, so Localize resolves it at runtime rather
than depending on it in return — add `{:calendrical, "~> 1.0"}` to your
dependencies to use this function.

### Arguments

* `string` is a string in any shape the locale accepts, including the
  locale's CLDR short, medium, long and full patterns and ISO 8601.

* `options` is a keyword list of options.

### Options

* `:locale` is a locale identifier. The default is the locale returned by
  `Localize.get_locale/0`.

* Remaining options are passed to `Calendrical.Date.parse/2`, which
  documents them.

### Returns

* `{:ok, value}` where `value` is a `t:Date.t()` , or

* `{:error, exception}` if the string does not parse, or a
  `t:Localize.DependencyRequiredError.t/0` if `calendrical` is not among
  the application's dependencies.

### Examples

Shown rather than run as doctests: `calendrical` is not a dependency of
Localize itself, so the call does not resolve in this package's own tests.

    Localize.Date.parse("22.03.2026", locale: :de)
    #=> {:ok, ~D[2026-03-22]}

    Localize.Date.parse("March 22, 2026", locale: :en)
    #=> {:ok, ~D[2026-03-22]}

# `to_parts`

```elixir
@spec to_parts(map(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, Exception.t()}
```

Formats a date into typed parts, mirroring ECMA-402's `formatToParts`.

The parts concatenate to exactly the string `to_string/2` produces with the same options. Each pattern field is tagged with its type: `:year`, `:month`, `:day`, `:weekday`, `:era`, and `:literal` for separators.

### Arguments

* `date` is a `t:Date.t/0` or any map with date keys.

* `options` is a keyword list of options.

### Options

See `to_string/2` for the supported options.

### Returns

* `{:ok, parts}` where `parts` is a list of `%{type: atom(), value: String.t()}` maps.

* `{:error, exception}` if the date cannot be formatted.

### Examples

    iex> Localize.Date.to_parts(~D[2017-07-10], locale: :en)
    {:ok,
     [
       %{type: :month, value: "Jul"},
       %{type: :literal, value: " "},
       %{type: :day, value: "10"},
       %{type: :literal, value: ", "},
       %{type: :year, value: "2017"}
     ]}

# `to_parts!`

```elixir
@spec to_parts!(map(), Keyword.t()) :: [%{type: atom(), value: String.t()}]
```

Same as `to_parts/2` but raises on error.

### Arguments

* `date` is a `t:Date.t/0` or any map with date keys.

* `options` is a keyword list of options. See `to_parts/2`.

### Returns

* A list of `%{type: atom(), value: String.t()}` maps.

### Raises

* Raises an exception if the date cannot be formatted.

### Examples

    iex> Localize.Date.to_parts!(~D[2017-07-10], locale: :en) |> length()
    5

# `to_string`

```elixir
@spec to_string(map(), Keyword.t()) :: {:ok, String.t()} | {:error, Exception.t()}
```

Formats a date according to a CLDR format pattern.

### Arguments

* `date` is a `t:Date.t/0` or any map with one or more of
  `:year`, `:month`, `:day` keys.

* `options` is a keyword list of options.

### Options

* `:format` is a standard format name (`:short`, `:medium`,
  `:long`, `:full`), a format skeleton atom, or a format
  pattern string. The default is `:medium` for full dates.
  For partial dates the format is derived from the available
  fields.

* `:locale` is a locale identifier. The default is `:en`.

* `:number_system` is a CLDR numbering system name (for example, `:thai`). All numeric fields render in that system; a `-u-nu-` locale extension may be used instead. The default is the locale's number system.

* `:prefer` selects between CLDR `alt` variants. Accepts an
  atom or a list of atoms in priority order. Recognised values:
  `:standard` / `:variant` (locales like en-CA publish both an
  ISO pattern `"y-MM-dd"` and a locale-variant `"d/M/yy"`),
  and `:unicode` / `:ascii` (NBSP and curly quotes vs ASCII).
  Examples: `prefer: :variant`, `prefer: [:variant, :ascii]`.
  The default is `[:standard, :unicode]`.

### Returns

* `{:ok, formatted_string}` on success.

* `{:error, exception}` if the date cannot be formatted.

### Examples

    iex> Localize.Date.to_string(~D[2017-07-10], locale: :en)
    {:ok, "Jul 10, 2017"}

    iex> Localize.Date.to_string(~D[2017-07-10], format: :full, locale: :en)
    {:ok, "Monday, July 10, 2017"}

    iex> Localize.Date.to_string(~D[2017-07-10], format: :short, locale: :en)
    {:ok, "7/10/17"}

    iex> Localize.Date.to_string(~D[2017-07-10], format: :short, locale: :fr)
    {:ok, "10/07/2017"}

    iex> Localize.Date.to_string(%{year: 2024, month: 6}, format: :yMMM, locale: :fr)
    {:ok, "juin 2024"}

# `to_string!`

```elixir
@spec to_string!(map(), Keyword.t()) :: String.t()
```

Same as `to_string/2` but raises on error.

### Arguments

* `date` is a `t:Date.t/0` or any map with one or more of
  `:year`, `:month`, `:day` keys.

* `options` is a keyword list of options.

### Options

See `to_string/2` for the supported options.

### Returns

* A formatted string.

* Raises an exception if the date cannot be formatted.

### Examples

    iex> Localize.Date.to_string!(~D[2017-07-10], locale: :en)
    "Jul 10, 2017"

    iex> Localize.Date.to_string!(%{year: 2024, month: 6}, format: :yMMM, locale: :fr)
    "juin 2024"

---

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