Proposal: strftime-based calendar/datetime formatting

So there is no way to get the actual era name in strftime?

Looks like I have misunderstood how %EC works (at least on MAC OSX). It just returns the century years:

kip@Kips-iMac-Pro strftime % ./a.out '%EC'
Result string is "20"

Therefore I don’t see a compatible path forward for including era formatting in strftime/2.

I believe we can add %V but I would make it calendar specific. So once you change calendars, it will return the week number of said calendars. The default is of course ISO. Does strftime specify a way to get the week of year? Without week of year, I don’t see this being very useful.

About %U and %W, I am honestly not sure, as they seem to be based on gregorian calendars. What would they return for a japanese calendar, for example?

I agree with this proposal. day_of_era works but we will probably need to use year_of_era to implement all of the modifiers (except the %EC itself).

Regarding “(AD versus CE and BC versus BCE)”, let’s just pick whatever strftime uses/returns.

I like this proposal too but I wonder if it should simply be an option called :number_formatter. The number formatter is a function that receives the number as an integer and the padding, and it returns a string. You can replace the number formatter to use any numeric alphabet and padding that you want. This seems simpler overall. WDYT?

Thanks for writing these down @kip. If you want, we can proceed with a PR for era while we discuss the remaining topics.

With Calendar.strftime/2 being merged into Elixir master (from the NimbleStrftime lib) I’d like to open a proposal on some additional formatting options and gain community feedback.

There are three sub-proposals and any and all feedback is welcome.

Weeks (yes, again with the weeks conversation )

Linux strftime has formatting flags for weeks. These being:

   %U     The week number of the current year as a decimal number, range
          00 to 53, starting with the first Sunday as the first day of
          week 01.  See also %V and %W.  (Calculated from tm_yday and
          tm_wday.)

   %V     The ISO 8601 week number (see NOTES) of the current year as a
          decimal number, range 01 to 53, where week 1 is the first week
          that has at least 4 days in the new year.  See also %U and %W.
          (Calculated from tm_year, tm_yday, and tm_wday.)  (SU)

   %W     The week number of the current year as a decimal number, range
          00 to 53, starting with the first Monday as the first day of
          week 01.  (Calculated from tm_yday and tm_wday.)

Adding this formatting directives would require an update to the Calendar behaviour to provide support.

Options:

1. No need, don’t add
2. Just add %V for the ISO week number and add Calendar.iso_week_of_year/1 to the Calendar behaviour
3. Maximise compatibility, go with all three and add the callbacks

Add support for Era

Calendar.day_of_era/1 returns {day, era} but that’s an integer, not a display format. Calendar behaviour doesn’t do any display format translation today. The new Calendar.strftime/2 does display format translation for AM and PM (and variants). So one approach is to simply enhance Calendar.strftime/2 to also map Calendar.ISO eras 0 -> display_name and 1 -> display_name. And there would need to be agreement on display name (AD versus CE and BC versus BCE).

Era isn’t used in day-to-day formatting for Gregorian calendars except for dates before year 1. It is used as a standard part of formatting Japanese calendars and for some format of Chinese calendars (and derivatives on the 60 year cycle).

strftime defines the following directives:

These can be implemented without a change to the calendar behaviour if Calendar.strftime/2 treats era like it treats am/pm and provides an internal translation. It would perhaps be better that both of these (ie am/pm and era translations became behaviours since that would also help in international projects using Gettext or Cldr.

Options

1. Era? Who cares, forget about it
2. Compatibility is a good idea and implementation seems simple. Do it.
3. I care about calendars beyond Calendar.ISO so I need this (I’m not holding my breath on this one )

Localised number systems (ie not Latin alphabet)

strftime supports localising the date format to use non-latin alphabets. These is also supported in ex_cldr and friends. The default for these directives is to use the Latin alphabet so implementing these directives is quite trivial. If no configuration is provided in options, use the fallback to the Latin characters.

The formatting directives are:

Options

1. Who cares about countries and people that don’t use the Latin alphabet. Forget it.
2. Good idea - easy to implement, no impact if I’m not doing non-latin alphabet code. Glad to see Elixir embracing global cultures (ok, I’m pitching I know )

@josevalim, all good. I think the only thing maybe missing is era, but I see that’s not part of the substitutions anyway.

For those looking to localise formatting with NimbleStrftime, there is now an ex_cldr function to generate the options for NimbleStrftime.format/3. ex_cldr_dates_times is another option for those looking for CLDR-based formatting.

MyApp.Cldr.Calendar.strftime_options!/2 (where MyApp is any Cldr backend module you’ve defined) provides these options. You’ll need to update to ex_cldr_calendars version 1.5.0.

Its a ! function because if the specified locale is unknown it will raise.

Examples

iex> NimbleStrftime.format(~D[2019-11-03], "%A, %b %d %Y", MyApp.Cldr.Calendar.strftime_options!())
"Sunday, Nov 03 2019"

iex> NimbleStrftime.format(~D[2019-11-03], "%A, %b %d %Y", MyApp.Cldr.Calendar.strftime_options!("fr")) ==
"dimanche, nov. 03 2019"

We have finally implemented a library based on this proposal: GitHub - dashbitco/nimble_strftime: A simple and fast strftime-based datetime formatter · GitHub

Everyone, please do give it a try in your application! And @kip, let us know if it provides the necessary hooks for i18n/l10n.

With my CLDR-based date/time formatter now finally out the door I look forward to serving configuration for strftime whenever its ready for a road test …

Ha, well I’d be happy to give it a shot.

That someone can even be you!

But yes, a formatter is just a module, so you can just define your own module if you want to.

I think there is more than enough rationale to justify something like this. To be honest, when I first got into Elixir, this was something I looked around for and just assumed it already existed.

Having used datetime formatters in a few languages, I think my favorite has been Moment.js (which isn’t strftime, and is closer to LDML). I even created a version for Elixir (sorry, never shared it). I think the formatting tokens are more intuitive than strftime.

For example, what I created looked like this:

DateTimeFormatter.format(datetime, "YYYY-MM-DD")
{:ok, "2018-12-22"}

DateTimeFormatter.format!(datetime, "M/D, h:mm a")
"12/22, 1:14 pm"

DateTimeFormatter.format(datetime, "[today is] dddd")
{:ok, "today is Saturday"}

One key difference is multiple characters for the token. Eg:

M              1 2 ... 11 12
Mo             1st 2nd ... 11th 12th
MM             01 02 ... 11 12
MMM            Jan Feb ... Nov Dec
MMMM           January February ... November December

That said, it sounds like you are proposing the ability to substitute formatters? So the default would be strftime, but someone could build a LDML formatter?