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

Formats a datetime 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, :hour, :minute, :second, :day_period, :time_zone_name, :era, :fractional_second, :literal, …). Standard formats, skeleton atoms, explicit pattern strings, and combined date+time wrappers all decompose.

Arguments

• datetime is a DateTime.t/0, NaiveDateTime.t/0, or any map with date and time 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 datetime cannot be formatted.

Examples

iex> Localize.DateTime.to_parts(~N[2017-07-10 14:30:00], format: :hm, locale: :en, prefer: :ascii)
{:ok,
 [
   %{type: :hour, value: "2"},
   %{type: :literal, value: ":"},
   %{type: :minute, value: "30"},
   %{type: :literal, value: " "},
   %{type: :day_period, value: "PM"}
 ]}

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

Same as to_parts/2 but raises on error.

Arguments

• datetime is a DateTime.t/0, NaiveDateTime.t/0, or any map with date and time 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 datetime cannot be formatted.

Examples

iex> Localize.DateTime.to_parts!(~N[2017-07-10 14:30:00], format: :hm, locale: :en, prefer: :ascii) |> length()
5

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

Formats a datetime according to a CLDR format pattern.

Arguments

• datetime is a DateTime.t/0, NaiveDateTime.t/0, or any map with date and time keys.

• options is a keyword list of options.

Options

• :format is a standard format name (:short, :medium, :long, :full) or a format pattern string. The default is :medium. It sets the width of the date and the time together; :date_format and :time_format override each axis separately.

• :date_format and :time_format are standard format names that set the width of the date half and the time half independently, each defaulting to :format. Use them for the common "full date, short time" pairing: date_format: :full, time_format: :short renders "Wednesday, April 8, 2026, 12:00 PM". When :date_format is given it also selects the wrapper width.

• :style selects the CLDR pattern that joins the date and the time. :default (the default) uses the standard wrapper ("April 8, 2026, 12:00:00 PM"); :at uses the locale's "at time" wrapper ("April 8, 2026 at 12:00:00 PM", de "8. April 2026 um 12:00:00"). CLDR defines the "at time" wrapper only for :full and :long, so :at falls back to the standard wrapper for :medium and :short.

• :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 (mostly time formats — NBSP and curly quotes vs ASCII-only). Examples: prefer: :variant, prefer: [:variant, :ascii]. The default is [:standard, :unicode].

Returns

• {:ok, formatted_string} on success.

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

Examples

iex> Localize.DateTime.to_string(~N[2017-07-10 14:30:00], locale: :en, prefer: :ascii)
{:ok, "Jul 10, 2017, 2:30:00 PM"}

iex> Localize.DateTime.to_string(~N[2017-07-10 14:30:00], format: :short, locale: :en, prefer: :ascii)
{:ok, "7/10/17, 2:30 PM"}

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

Same as to_string/2 but raises on error.

Arguments

• datetime is a DateTime.t/0, NaiveDateTime.t/0, or any map with date and time 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 datetime cannot be formatted.

Examples

iex> Localize.DateTime.to_string!(~N[2017-07-10 14:30:00], locale: :en, prefer: :ascii)
"Jul 10, 2017, 2:30:00 PM"

iex> Localize.DateTime.to_string!(~N[2017-07-10 14:30:00], format: :short, locale: :en, prefer: :ascii)
"7/10/17, 2:30 PM"