# `Localize.DateTime`
[🔗](https://github.com/elixir-localize/localize/blob/v0.6.0/lib/localize/datetime.ex#L1)

Provides localized formatting of `DateTime`, `NaiveDateTime`,
and datetime-like maps.

The primary function is `to_string/2` which accepts a datetime
value and an options keyword list. Format patterns are defined
in CLDR and described in
[TR35](http://unicode.org/reports/tr35/tr35-dates.html).

## Predefined formats

* `:short` — abbreviated date and time (e.g., "1/2/25, 3:04 PM").

* `:medium` — standard date and time (default).

* `:long` — includes time zone name.

* `:full` — verbose day-of-week, date, and time zone.

Custom CLDR skeleton strings and raw format patterns are also
supported via the `:format` option.

# `to_string`

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

Formats a datetime according to a CLDR format pattern.

### Arguments

* `datetime` is a `t:DateTime.t/0`, `t:NaiveDateTime.t/0`,
  or any map with date and time keys.

* `options` is a keyword list of options.

### Options

* `:format` is a standard format name (`:short`, `:medium`,
  `:long`, `:full`) or a format pattern string. The default
  is `:medium`.

* `: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 datetime cannot be formatted.

### Examples

    iex> Localize.DateTime.to_string(~N[2017-07-10 14:30:00], locale: :en, prefer: :ascii)
    {:ok, "Jul 10, 2017, 2:30:00 PM"}

    iex> Localize.DateTime.to_string(~N[2017-07-10 14:30:00], format: :short, locale: :en, prefer: :ascii)
    {:ok, "7/10/17, 2:30 PM"}

# `to_string!`

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

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

---

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