Add NimbleStrftime

[josevalim]

NimbleStfrtime was created to validate calendar formatting as a separate project before adding it to Elixir itself. This issue is to meant to track its inclusion once we get enough feedback.

Questions

The library is quite small and provides a single function, so addition should be relatively straight-forward. The only open question we have at the moment is, should be added as: Calendar.strftime/2 OR Calendar.format/2?

Other tasks

Once Calendar.format/2 is added, we will deprecate the :basic and :extended options from the ISO calendar and the ISO related APIs, keeping only the API that receives no such argument and returns the extended format.

PS: please do not send a PR for this, as the project is still under validation. Meanwhile we recommend everyone to give NimbleStrftime a try.

[kipcole9]

I've added <backend>.Cldr.Calendar.strftime_options!/1 to return a localised keyword list to support Calendar.format/2 and I have no issues with the API.

Its a ! method because its possible to pass an invalid locale and there's no way to signal an error return from the anonymous functions other than as an exception.

I am yet to return "preferred formats" because that would require translating between CLDR formats and strftime formats and its probably not worth it although it would provide for a largely automated localisation process for date and time formatting using the strftime format vocabulary.

I would like to include era as a localisable field if thats a reasonable ask. Not important for Calendar.ISO but useful for Julian and Japanese calendars for sure.

I personally like Calendar.format/2 over Calendar.strftime/2.

[Eiji7]

@josevalim I would like to vote for Calendar.strftime/2.

First of all such function name is more self-descriptive.

Secondly in case other format would become as popular as strftime then we can simply add it as a separate function without deprecate old format behaviour or doing something with user_options.

Finally format is too generic name and developer could expect support for other even less popular formats which may become a frequently asked question like for example:

Hey, I found Calendar.format/2 function and I'm curious if it supports also XYZ format. If not then I would like to ask if there are any plans to add support for it.

---

Of course we could later make user_options default to let's say: [type: :strftime], but this:

Calendar.format(datetime, "%y-%m-%d %I:%M:%S %p")
# and just for example:
Calendar.format(datetime, "#y-#m-#d #I:#M:#S #p", type: :strftime_hash)

would be more confusing for beginners comparing to:

Calendar.strftime(datetime, "%y-%m-%d %I:%M:%S %p")
# and again just for example:
Calendar.strftime_hash(datetime, "#y-#m-#d #I:#M:#S #p")

because of as already said above such function name is more self-descriptive.

[josevalim]

@GuSilverFlame would you like to send a PR that adds NimbleStrftime.format as Calendar.strftime to Elixir? :)

[kipcole9]

Looking forward to this making its way into Elixir. Any chance of considering an Era token for completeness?

[josevalim]

@kipcole9 does the original strftime do anything with Era? It has been a while, so I don't fully recall. :)

[GustavoSantosFe]

@GuSilverFlame would you like to send a PR that adds NimbleStrftime.format as Calendar.strftime to Elixir? :)

I'll start working on it right away! 😁

[kipcole9]

According to the Linux man page for strftime:

Some conversion specifications can be modified by preceding the conversion specifier character by the E or O modifier to indicate that an alternative format should be used. If the alternative format or specification does not exist for the current locale, the behavior will be as if the unmodified conversion specification were used. (SU)

The Single UNIX Specification mentions %Ec, %EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU, %OV, %Ow, %OW, %Oy, where the effect of the O modifier is to use alternative numeric symbols (say, roman numerals), and that of the E modifier is to use a locale-dependent alternative representation.

The table below summarises. I'd like to propose including the %E modifier. Although I'd also like the %O modifier, there is no other support in Elixir for non-arabic numerals so I believe this would be out of scope.

Specifier	Meaning
%Ec	Date/time for current era.
%EC	Era name.
%Ex	Date for current era.
%EX	Time for current era.
%Ey	Era year. This is the offset from the base year.
%EY	Year for current era.
--	--
%Od	Represents the day of the month, using the locale's alternative numeric symbols, filled as needed with leading 0's if an alternative symbol for 0 exists. If an alternative symbol for 0 does not exist, the %Od modified conversion specifier uses leading space characters.
%Oe	Represents the day of the month, using the locale's alternative numeric symbols, filled as needed with leading 0's if an alternative symbol for 0 exists. If an alternative symbol for 0 does not exist, the %Oe modified conversion specifier uses leading space characters.
%OH	Represents the hour in 24-hour clock time, using the locale's alternative numeric symbols.
%OI	Represents the hour in 12-hour clock time, using the locale's alternative numeric symbols.
%Om	Represents the month, using the locale's alternative numeric symbols.
%OM	Represents the minutes, using the locale's alternative numeric symbols.
%OS	Represents the seconds, using the locale's alternative numeric symbols.
%Ou	Represents the weekday as a number using the locale's alternative numeric symbols.
%OU	Represents the week number of the year, using the locale's alternative numeric symbols. Sunday is considered the first day of the week. Use the rules corresponding to the %U conversion specifier.
%OV	Represents the week number of the year (Monday as the first day of the week, rules corresponding to %V) using the locale's alternative numeric symbols.
%Ow	Represents the number of the weekday (with Sunday equal to 0), using the locale's alternative numeric symbols.
%OW	Represents the week number of the year using the locale's alternative numeric symbols. Monday is considered the first day of the week. Use the rules corresponding to the %W conversion specifier.
%Oy	Represents the year (offset from %C) using the locale's alternative numeric symbols.

[josevalim]

@kipcole9 excellent, thanks! Let's merge nimble_strftime as is and then we can discuss a PR with era extensions afterwards. :)

[kipcole9]

Happy to work on a followup PR after merging if there is support to do so.

[josevalim]

Thanks @GuSilverFlame! I will close this in favor of the PR!

@kipcole9 could you please send a more detailed proposal for the era changes? Feel free to open up a new issue here. In particular, I am curious if we need new callbacks in the Calendar module in order to provide all %Ec, %Ex and so on variants or if our current callbacks cover it. Then we can proceed to the PR!