Add functions for time formatting

[alt-graph]

In the DOOCS clientlib we have functions for formatting local time:

/**
 * Convert a timestamp into local time and format it into a std::string using strftime()
 * format specifiers.
 *
 * Due to the limitations of strftime(), this function does not support sub-second
 * output precision.
 *
 * \param ts   The timestamp to be formatted.
 * \param fmt  A format string following the specifications of strftime(), see
 *             https://en.cppreference.com/w/cpp/chrono/c/strftime . If fmt is a null
 *             pointer, an empty string is returned. The default format generates an
               ISO 8601 compliant date-time string.
 * \returns a string with the formatted output or an empty string if an error occurred.
 */
std::string format_localtime (Timestamp ts, const char *fmt = "%Y-%m-%dT%H:%M:%S");
std::string format_localtime (std::time_t t, const char *fmt = "%Y-%m-%dT%H:%M:%S");

Such functions are useful also for other projects (both for UTC and local times). I'd say we could use them in GUL14.

[Finii]

Hmm, I'd like to see Howards date as a 'backport-ish' thing, like optional.
It's single header. I usually just grab that one file and throw it into my source-tree, but would rather like to have it in GUL instead.

Newer description with other date-time stuff here: https://github.com/HowardHinnant/date

And it has subsecond resolution. Usually use it like this

    auto tp = system_clock::now();
    std::cout << tp << '\n';

    2015-04-19 18:24:42.770911

Of course you can generate the unreadable ISO 8601 or, as I prefer RFCs over ISO, RFC 3389 strings.

So, if you look again at the RFC document. RFC 3339 use/follow the ISO 8601 profile for the Internet DateTime. Clearly stated in chapter 5.6

So actually, there are no big differences between Date ISO 8601. The only small thing that makes these 2 different is the “T” syntax between date and time. ISO 8601 uses the “T” character to separate the date and time. In RFC 3339, you can replace the “T” character with only using space.

For example:

# This is acceptable in ISO 8601 and RFC 3339 (with T)
2019-10-12T07:20:50.52Z
# This is only accepted in RFC 3339 (without T)
2019-10-12 07:20:50.52Z

Source here for an interested reader

Of course any formatting is possible, as with the C style format string, by std::formatter I mean, no that is C++20, but date::format

If we need timezones, that is another header file. I never used this.

[alt-graph]

I would support adding the date header. It offers a lot of functionality that is missing before C++20.

However, I would still argue that there is a strong use case for a format_localtime()/format_gmtime()-ish function because it allows you to format your date/time with a single command. As far as I understand, date only gives you the bits and pieces to do that yourself, plus a stream operator with a default format.

[Finii]

Hmm, some examples

#include <iostream>
#include <chrono>
#include "date/date.h"
#include "date/tz.h"

int main() {
        auto now = std::chrono::system_clock::now();
        std::cout << "ISO:   " << date::format("%Y-%m-%dT%H:%M:%OS", now) << '\n';
        std::cout << "RFC:   " << date::format("%Y-%m-%d %H:%M:%OS", now) << '\n';
        std::cout << "RFC:   " << date::format("%Y-%m-%d %H:%M:%OS%Z", now) << '\n';
        std::cout << "RFC:   " << date::format("%Y-%m-%d %H:%M:%OS %Z", now) << '\n';
        std::cout << "hires: " << date::format("%Y-%m-%d %H:%M:%S %Z", now) << '\n';

        auto now_circa = date::floor<std::chrono::seconds>(now);
        std::cout << "hires: " << date::format("%Y-%m-%d %H:%M:%S %Z", now_circa) << '\n';

        std::string x = date::format("%Y-%m-%d %H:%M:%S %Z", now);
        std::cout << "str:   " << x << '\n';

        using namespace date;
        std::cout << "auto:  " << now << '\n';

        // following code uses tz.h
        std::cout << "local: " << date::make_zoned(date::current_zone(), now) << '\n';
}

$ g++ test.cc tz.cpp -DUSE_OS_TZDB && ./a.out
ISO:   2022-07-19T19:47:25
RFC:   2022-07-19 19:47:25
RFC:   2022-07-19 19:47:25UTC
RFC:   2022-07-19 19:47:25 UTC
hires: 2022-07-19 19:47:25.714839880 UTC
hires: 2022-07-19 19:47:25 UTC
str:   2022-07-19 19:47:25.714839880 UTC
auto:  2022-07-19 19:47:25.714839880
local: 2022-07-19 21:47:25.714839880 CEST

$ ls -R
.:
a.out  date  test.cc  tz.cpp

./date:
date.h  tz.h  tz_private.h

Links to the four files are here:
https://github.com/HowardHinnant/date/blob/master/include/date/date.h
https://github.com/HowardHinnant/date/blob/master/include/date/tz.h
https://github.com/HowardHinnant/date/blob/master/include/date/tz_private.h (*)
https://github.com/HowardHinnant/date/blob/master/src/tz.cpp (*)

(*) Only needed for the library

[alt-graph]

Oh, I missed date::format(). In that case, I agree that the date header would render the other functions obsolete. It is just a bit on the heavy side with >8000 LOC. That would be by far our biggest header with the exception of Catch2.

[alt-graph]

I created a merge request: #9