Search documentation of Localize

# Localize.Interval (Localize v0.39.0)

Copy Markdown View Source

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.

## Summary

### Functions

date_styles()

Returns the locale-independent date interval style configurations.

greatest_difference(from, to)

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

split_interval(interval)

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

to_string(from, to, options \\ [])

Formats a date interval as a localized string.

to_string!(from, to, options \\ [])

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

## Functions

# date_styles()

    @spec date_styles() :: %{
      month: %{short: :M, medium: :MMM, long: :MMM, full: :MMM},
      month_and_day: %{short: :Md, medium: :MMMd, long: :MMMEd, full: :MMMEd},
      year_and_month: %{short: :yM, medium: :yMMM, long: :yMMMM, full: :yMMMM}
    }

Returns the locale-independent date interval style configurations.

Only the non-default `:style` options (`:month`, `:month_and_day`, `:year_and_month`) appear here. The default `:date` style is resolved per-locale, mirroring `Localize.Date.to_string/2`'s style → skeleton mapping for that locale.

# greatest_difference(from, to)

    @spec greatest_difference(map(), map()) ::
      {:ok, :y | :M | :d | :H | :m} | {:error, Exception.t()}

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, %Localize.NoPracticalDifferenceError{}}` if the values are equal at every field considered.

# split_interval(interval)

    @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(from, to, options \\ [])

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

Formats a date interval as a localized string.

### Arguments

- `from` is a `Date.t/0`.

- `to` is a `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!(from, to, options \\ [])

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

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