Intl.DateTimeFormat (Intl v0.2.0)

Locale-sensitive date and time formatting, modelled on Intl.DateTimeFormat.

Formats dates, times, and datetimes according to locale conventions. Accepts Date, Time, DateTime, and NaiveDateTime structs.

Delegates to Localize.DateTime, Localize.Date, and Localize.Time for the underlying formatting.

Summary

Functions

format(value, options \\ [])

Formats a date, time, or datetime value according to locale conventions.

format!(value, options \\ [])

Formats a date, time, or datetime value, raising on error.

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

Formats a date/time range according to locale conventions.

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

Formats a date/time range, raising on error.

Functions

format(value, options \\ [])

@spec format(
  Date.t() | Time.t() | DateTime.t() | NaiveDateTime.t() | map(),
  Keyword.t()
) ::
  {:ok, String.t()} | {:error, term()}

Formats a date, time, or datetime value according to locale conventions.

Arguments

value is a Date, Time, DateTime, or NaiveDateTime struct, or a map with date and/or time keys.
options is a keyword list of options.

Options

:locale is a locale identifier string or atom. The default is the current process locale.
:date_style is :full, :long, :medium, or :short. Provides a predefined date format. Cannot be combined with individual component options.
:time_style is :full, :long, :medium, or :short. Provides a predefined time format. Cannot be combined with individual component options.
:weekday is :long, :short, or :narrow.
:year is :numeric or :"2-digit".
:month is :numeric, :"2-digit", :long, :short, or :narrow.
:day is :numeric or :"2-digit".
:hour is :numeric or :"2-digit".
:minute is :numeric or :"2-digit".
:second is :numeric or :"2-digit".
:time_zone is a time zone identifier string (for example, "America/New_York").
:calendar is a calendar type atom (for example, :gregorian).

Returns

{:ok, formatted_string} on success.
{:error, reason} if the value or options are invalid.

Examples

iex> Intl.DateTimeFormat.format(~D[2017-07-10], locale: :en, date_style: :full)
{:ok, "Monday, July 10, 2017"}

iex> Intl.DateTimeFormat.format(~D[2017-07-10], locale: :en, date_style: :short)
{:ok, "7/10/17"}

iex> Intl.DateTimeFormat.format(~N[2017-07-10 14:30:00], locale: :en, date_style: :medium, time_style: :short, prefer: :ascii)
{:ok, "Jul 10, 2017, 2:30 PM"}

format!(value, options \\ [])

@spec format!(
  Date.t() | Time.t() | DateTime.t() | NaiveDateTime.t() | map(),
  Keyword.t()
) ::
  String.t() | no_return()

Formats a date, time, or datetime value, raising on error.

Same as format/2 but returns the string directly or raises.

Arguments

value is a Date, Time, DateTime, or NaiveDateTime struct, or a map with date and/or time keys.
options is a keyword list of options.

Returns

A formatted string.

Examples

iex> Intl.DateTimeFormat.format!(~D[2017-07-10], locale: :en, date_style: :full)
"Monday, July 10, 2017"

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

@spec format_range(map(), map(), Keyword.t()) :: {:ok, String.t()} | {:error, term()}

Formats a date/time range according to locale conventions.

Arguments

from is the start date, time, or datetime.
to is the end date, time, or datetime.
options is a keyword list of options. Accepts the same options as format/2.

Returns

{:ok, formatted_string} on success.
{:error, reason} if the values or options are invalid.

Examples

iex> Intl.DateTimeFormat.format_range(~D[2017-07-10], ~D[2017-07-15], locale: :en)
{:ok, "Jul 10 – 15, 2017"}

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

@spec format_range!(map(), map(), Keyword.t()) :: String.t() | no_return()

Formats a date/time range, raising on error.

Same as format_range/3 but returns the string directly or raises.

Arguments

from is the start date, time, or datetime.
to is the end date, time, or datetime.
options is a keyword list of options.

Returns

A formatted string.

Examples

iex> Intl.DateTimeFormat.format_range!(~D[2017-07-10], ~D[2017-07-15], locale: :en)
"Jul 10 – 15, 2017"