# `Localize.Date`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.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).

# `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`.

* `:prefer` is `:unicode` or `:ascii` for variant selection.
  The default is `: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.

### 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*