# `Timex.Format.DateTime.Formatter`
[🔗](https://github.com/bitwalker/timex/blob/4.0.0/lib/format/datetime/formatter.ex#L1)

This module defines the behaviour for custom DateTime formatters.

# `format`

```elixir
@callback format(date :: Timex.Types.calendar_types(), format_string :: String.t()) ::
  {:ok, String.t()} | {:error, term()}
```

# `format!`

```elixir
@callback format!(date :: Timex.Types.calendar_types(), format_string :: String.t()) ::
  String.t() | no_return()
```

# `lformat`

```elixir
@callback lformat(
  date :: Timex.Types.calendar_types(),
  format_string :: String.t(),
  locale :: String.t()
) ::
  {:ok, String.t()} | {:error, term()}
```

# `lformat!`

```elixir
@callback lformat!(
  date :: Timex.Types.calendar_types(),
  format_string :: String.t(),
  locale :: String.t()
) ::
  String.t() | no_return()
```

# `tokenize`

```elixir
@callback tokenize(format_string :: String.t()) ::
  {:ok, [Timex.Parse.DateTime.Tokenizers.Directive.t()]} | {:error, term()}
```

# `format`

```elixir
@spec format(Timex.Types.valid_datetime(), String.t(), atom() | nil) ::
  {:ok, String.t()} | {:error, term()}
```

Formats a Date, DateTime, or NaiveDateTime as a string, using the provided format
string and formatter. If a formatter is not provided, the formatter
used is `Timex.Format.DateTime.Formatters.DefaultFormatter`.

Formatting will use the configured default locale, "en" if no other default is given.

# `format!`

```elixir
@spec format!(Timex.Types.valid_datetime(), String.t(), atom() | nil) ::
  String.t() | no_return()
```

Formats a Date, DateTime, or NaiveDateTime as a string, using the provided format
string and formatter. If a formatter is not provided, the formatter
used is `Timex.Format.DateTime.Formatters.DefaultFormatter`.

Formatting will use the configured default locale, "en" if no other default is given.

If an error is encountered during formatting, `format!` will raise.

# `format_token`

```elixir
@spec format_token(atom(), Timex.Types.calendar_types(), list(), list(), list()) ::
  String.t() | {:error, term()}
```

Given a token (as found in `Timex.Parsers.Directive`), and a Date, DateTime, or NaiveDateTime struct,
produce a string representation of the token using values from the struct, using the default locale.

# `format_token`

```elixir
@spec format_token(
  String.t(),
  atom(),
  Timex.Types.calendar_types(),
  list(),
  list(),
  list()
) ::
  String.t() | {:error, term()}
```

Given a token (as found in `Timex.Parsers.Directive`), and a Date, DateTime, or NaiveDateTime struct,
produce a string representation of the token using values from the struct.

# `lformat`

```elixir
@spec lformat(Timex.Types.valid_datetime(), String.t(), String.t(), atom() | nil) ::
  {:ok, String.t()} | {:error, term()}
```

Formats a Date, DateTime, or NaiveDateTime as a string, using the provided format string,
locale, and formatter.

If the locale provided does not have translations, "en" is used by default.

If a formatter is not provided, the formatter used is `Timex.Format.DateTime.Formatters.DefaultFormatter`

# `lformat!`

```elixir
@spec lformat!(Timex.Types.valid_datetime(), String.t(), String.t(), atom() | nil) ::
  String.t() | no_return()
```

Formats a Date, DateTime, or NaiveDateTime as a string, using the provided format string,
locale, and formatter. If the locale does not have translations, "en" will be used by
default.

If a formatter is not provided, the formatter used is `Timex.Format.DateTime.Formatters.DefaultFormatter`

If an error is encountered during formatting, `lformat!` will raise

# `validate`

```elixir
@spec validate(String.t(), atom() | nil) :: :ok | {:error, term()}
```

Validates the provided format string, using the provided formatter,
or if none is provided, the default formatter. Returns `:ok` when valid,
or `{:error, reason}` if not valid.

---

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