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

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