Skip to content

Latest commit

 

History

History
107 lines (73 loc) · 5.66 KB

README.md

File metadata and controls

107 lines (73 loc) · 5.66 KB
Raw

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"