Settings View Source Calendar.strftime options generator for CLDR

Calendar.strftime/3 has been available since Elixir 1.11 to provide date/datetime formatting using the principles that date back to at least 1978.

The functions in this library are intended to serve options to Calendar.strftime/3 to support localisation of dates/datetimes leveraging the content in CLDR. Therefore a developer can take advantage of the built-in localised formats from CLDR with well-known strftime formatting strings.

Installation

The package can be installed by adding cldr_strftime to your list of dependencies in mix.exs:

def deps do
  [
    {:ex_cldr_strftime, "~> 0.2.0"}
  ]
end

Configuration

Update your ex_cldr backend module to include the provider module Cldr.Strftime. For example:

defmodule MyApp.Cldr do
  use Cldr,
    locales: ["en", "fr", "af", "ja", "de", "pl", "th"],
    providers: [Cldr.Number, Cldr.Calendar, Cldr.DateTime, Cldr.Strftime]
end

Documentation is available at https://hexdocs.pm/cldr_strftime.

Keyword Options returned

In accordance with the options defined for Calendar.strftime/3, Cldr.Strftime.strftime_options!/2 returns the following keyword list:

• :preferred_datetime - a string for the preferred format to show datetimes,

• :preferred_date - a string for the preferred format to show dates.

• :preferred_time - a string for the preferred format to show times.

• :am_pm_names - a function that receives either :am or :pm and returns the name of the period of the day

• :month_names - a function that receives a number and returns the name of the corresponding month.

• :abbreviated_month_names - a function that receives a number and returns the abbreviated name of the corresponding month.

• :day_of_week_names - a function that receives a number and returns the name of the corresponding day of week.

• :abbreviated_day_of_week_names - a function that receives a number and returns the abbreviated name of the corresponding day of week

CLDR format translation

CLDR formats dates, times and date times using a different formatting system to that of Calendar.strftime/3. The CLDR formats are translated at compile time according to the following table. Since them formats are translated at compile time, performance is comparable to using native Calendar.strftime/3formats natively.

Calendar.strftime/3 allows for a set of options to guide formatting

Example usage

These examples use the %c, %x and %X format flags which means "use the preferred_* option if provided".

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%x", Cldr.Strftime.strftime_options!()
"Aug 26, 2019"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%X", Cldr.Strftime.strftime_options!()
"13:52:06 PM"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%c", Cldr.Strftime.strftime_options!()
"Aug 26, 2019, 13:52:06 PM"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%c", Cldr.Strftime.strftime_options!("ja")
"2019/08/26 13:52:06"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%c", Cldr.Strftime.strftime_options!("ja", format: :long)
"2019年08月26日 13:52:06 +0000"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%c", Cldr.Strftime.strftime_options!("pl")
"26 sie 2019, 13:52:06"

iex> Calendar.strftime ~U[2019-08-26 13:52:06.0Z], "%c", Cldr.Strftime.strftime_options!("pl", format: :long)
"26 sierpnia 2019 13:52:06 +0000"