@spec to_parts(map(), Keyword.t()) ::
  {:ok, [%{type: atom(), value: String.t()}]} | {:error, Exception.t()}

Formats a date into typed parts, mirroring ECMA-402's formatToParts.

The parts concatenate to exactly the string to_string/2 produces with the same options. Each pattern field is tagged with its type: :year, :month, :day, :weekday, :era, and :literal for separators.

Arguments

• date is a Date.t/0 or any map with date keys.

• options is a keyword list of options.

Options

See to_string/2 for the supported options.

Returns

• {:ok, parts} where parts is a list of %{type: atom(), value: String.t()} maps.

• {:error, exception} if the date cannot be formatted.

Examples

iex> Localize.Date.to_parts(~D[2017-07-10], locale: :en)
{:ok,
 [
   %{type: :month, value: "Jul"},
   %{type: :literal, value: " "},
   %{type: :day, value: "10"},
   %{type: :literal, value: ", "},
   %{type: :year, value: "2017"}
 ]}

@spec to_parts!(map(), Keyword.t()) :: [%{type: atom(), value: String.t()}]

Same as to_parts/2 but raises on error.

Arguments

• date is a Date.t/0 or any map with date keys.

• options is a keyword list of options. See to_parts/2.

Returns

• A list of %{type: atom(), value: String.t()} maps.

Raises

• Raises an exception if the date cannot be formatted.

Examples

iex> Localize.Date.to_parts!(~D[2017-07-10], locale: :en) |> length()
5

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

Formats a date according to a CLDR format pattern.

Arguments

• date is a Date.t/0 or any map with one or more of :year, :month, :day keys.

• options is a keyword list of options.

Options

• :format is a standard format name (:short, :medium, :long, :full), a format skeleton atom, or a format pattern string. The default is :medium for full dates. For partial dates the format is derived from the available fields.

• :locale is a locale identifier. The default is :en.

• :number_system is a CLDR numbering system name (for example, :thai). All numeric fields render in that system; a -u-nu- locale extension may be used instead. The default is the locale's number system.

• :prefer selects between CLDR alt variants. Accepts an atom or a list of atoms in priority order. Recognised values: :standard / :variant (locales like en-CA publish both an ISO pattern "y-MM-dd" and a locale-variant "d/M/yy"), and :unicode / :ascii (NBSP and curly quotes vs ASCII). Examples: prefer: :variant, prefer: [:variant, :ascii]. The default is [:standard, :unicode].

Returns

• {:ok, formatted_string} on success.

• {:error, exception} if the date cannot be formatted.

Examples

iex> Localize.Date.to_string(~D[2017-07-10], locale: :en)
{:ok, "Jul 10, 2017"}

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

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

iex> Localize.Date.to_string(~D[2017-07-10], format: :short, locale: :fr)
{:ok, "10/07/2017"}

iex> Localize.Date.to_string(%{year: 2024, month: 6}, format: :yMMM, locale: :fr)
{:ok, "juin 2024"}

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

Same as to_string/2 but raises on error.

Arguments

• date is a Date.t/0 or any map with one or more of :year, :month, :day keys.

• options is a keyword list of options.

Options

See to_string/2 for the supported options.

Returns

• A formatted string.

• Raises an exception if the date cannot be formatted.

Examples

iex> Localize.Date.to_string!(~D[2017-07-10], locale: :en)
"Jul 10, 2017"

iex> Localize.Date.to_string!(%{year: 2024, month: 6}, format: :yMMM, locale: :fr)
"juin 2024"