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

Parses a localized date string.

Parsing lives in the companion calendrical package, which carries the calendar systems Localize formats for. calendrical depends on Localize, so Localize resolves it at runtime rather than depending on it in return — add {:calendrical, "~> 1.0"} to your dependencies to use this function.

Arguments

• string is a string in any shape the locale accepts, including the locale's CLDR short, medium, long and full patterns and ISO 8601.

• options is a keyword list of options.

Options

• :locale is a locale identifier. The default is the locale returned by Localize.get_locale/0.

• Remaining options are passed to Calendrical.Date.parse/2, which documents them.

Returns

• {:ok, value} where value is a t:Date.t() , or

• {:error, exception} if the string does not parse, or a Localize.DependencyRequiredError.t/0 if calendrical is not among the application's dependencies.

Examples

Shown rather than run as doctests: calendrical is not a dependency of Localize itself, so the call does not resolve in this package's own tests.

Localize.Date.parse("22.03.2026", locale: :de)
#=> {:ok, ~D[2026-03-22]}

Localize.Date.parse("March 22, 2026", locale: :en)
#=> {:ok, ~D[2026-03-22]}

@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"