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

Formats date and time intervals as localized strings.

Interval formats produce strings like "Jan 10 – 12, 2008" from
two dates, rather than repeating "Jan 10, 2008 – Jan 12, 2008".
The format is selected based on the greatest calendar field
difference between the start and end values.

# `date_styles`

```elixir
@spec date_styles() :: %{
  date: %{short: :yMd, medium: :yMMMd, long: :yMMMEd},
  month: %{short: :M, medium: :MMM, long: :MMM},
  month_and_day: %{short: :Md, medium: :MMMd, long: :MMMEd},
  year_and_month: %{short: :yM, medium: :yMMM, long: :yMMMM}
}
```

Returns the date interval style configurations.

# `greatest_difference`

```elixir
@spec greatest_difference(map(), map()) ::
  {:ok, :y | :M | :d | :H | :m} | {:error, :no_practical_difference}
```

Returns the greatest calendar field difference between
two dates or datetimes.

### Arguments

* `from` is a date or datetime map.

* `to` is a date or datetime map.

### Returns

* `{:ok, field}` where field is `:y`, `:M`, `:d`, `:H`, or `:m`.

* `{:error, :no_practical_difference}` if the values are equal.

# `split_interval`

```elixir
@spec split_interval(String.t()) :: {:ok, [String.t()]} | {:error, Exception.t()}
```

Splits an interval format string into `[left, right]` halves
at the point where a format character repeats.

# `to_string`

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

Formats a date interval as a localized string.

### Arguments

* `from` is a `t:Date.t/0`.

* `to` is a `t:Date.t/0`.

* `options` is a keyword list of options.

### Options

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

* `:format` is `:short`, `:medium`, or `:long`. The default
  is `:medium`.

* `:style` is `:date`, `:month`, `:month_and_day`, or
  `:year_and_month`. The default is `:date`.

### Returns

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

* `{:error, exception}` on failure.

### Examples

    iex> {:ok, result} = Localize.Interval.to_string(~D[2022-04-22], ~D[2022-04-25], locale: :en)
    iex> String.contains?(result, "Apr")
    true

    iex> {:ok, result} = Localize.Interval.to_string(~D[2022-01-15], ~D[2022-03-20], locale: :en)
    iex> String.contains?(result, "Jan") and String.contains?(result, "Mar")
    true

# `to_string!`

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

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

---

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