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.

Strftime	CLDR	Description	Examples (in ISO)
a	E,EE,EEE	Abbreviated name of day	Mon
A	EEEE	Full name of day	Monday
b	MMM	Abbreviated month name	Jan
B	MMMM	Full month name	January
d	d	Day of the month	01, 12
H	h	Hour using a 24-hour clock	00, 23
I	H	Hour using a 12-hour clock	01, 12
j	DDD	Day of the year	001, 366
m	MM	Month	01, 12
M	mm	Minute	00, 59
p	a,aa,aaa	"AM" or "PM" (noon is "PM", midnight as "AM")	AM, PM
q	Q	Quarter	1, 2, 3, 4
S	ss	Second	00, 59, 60
u	s	Day of the week	1 (Monday), 7 (Sunday)
y	YY	Year as 2-digits	01, 01, 86, 18
Y	YYYY	Year	-0001, 0001, 1986
z	ZZZZ	+hhmm/-hhmm time zone offset from UTC (empty string if naive)	+0300, -0530
Z	V, VV	Time zone abbreviation (empty string if naive)	CET, BRST

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"