std::chrono...ay::operator(3)

💖 std::chrono...ay::operator(3) 💖

Bestie, welcome to this manual page from the C++ Standard Libary — yes, that’s the manual-name vibe right there — and it’s all about the conversion operators on std::chrono::year_month_day: the sys_days one and the local_days one. Calendar math, but make it main-character energy. 🗓️✨

---

🌟 NAME 🌟

Officially, the NAME block is std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator — std::chrono::year_month_day::operatorsys_days,std::chrono::year_month_day::operator. Yep, it literally repeats the exact same thing; that’s the bit. 💅

---

✨ Synopsis ✨

Two overloads, both constexpr, both noexcept, both (since C++20). Slay. 🎀

constexpr operator std::chrono::sys_days() const noexcept;

(1) (since C++20)

constexpr explicit operator std::chrono::local_days() const noexcept;

(2) (since C++20)

Okay so both of these convert *this to a std::chrono::time_point representing the same date as this year_month_day. Obsessed. 💖

1. If ok() is true, the return value holds a count of days from the std::chrono::system_clock epoch (1970-01-01) to *this. The result is negative if *this represent a date prior to it. Otherwise, if the stored year and month are valid (year().ok() && month().ok() is true), then the returned value is sys_days(year()/month()/1d) + (day() - 1d). Otherwise (if year().ok() && month().ok() is false), the return value is unspecified. A std::chrono::sys_days in the range [std::chrono::days{-12687428}, std::chrono::days{11248737}], when converted to year_month_day and back, yields the same value. 🔥
2. Same as (1) but returns local_days instead. Equivalent to return local_days(sys_days(*this).time_since_epoch());. 🦋

---

🧚 Notes 🧚

Converting to std::chrono::sys_days and back can be used to normalize a year_month_day that contains an invalid day but a valid year and month:

using namespace std::chrono;
auto ymd = 2017y/January/0;
ymd = sys_days{ymd};
// ymd is now 2016y/December/31

Normalizing the year and month can be done by adding (or subtracting) zero std::chrono::months:

using namespace std::chrono;
constexpr year_month_day normalize(year_month_day ymd)
{
    ymd += months{0}; // normalizes year and month
    return sys_days{ymd}; // normalizes day
}
static_assert(normalize(2017y/33/59) == 2019y/10/29);

That static_assert ate and left no crumbs, ngl. 😭💜

---

🌈 Example 🌈

// Run this code — like, literally run it, bestie:

#include <chrono>
#include <iostream>

int main()
{
    using namespace std::chrono;
    const auto today =
       sys_days{std::chrono::floor<days>(system_clock::now())};
    for (const year_month_day ymd : {{November/15/2020},
       {November/15/2120}, today})
    {
        std::cout << ymd;
        const auto delta = (sys_days{ymd} - today).count();
        (delta < 0) ? std::cout << " was " << -delta << " day(s) ago\n"
                    : (delta > 0) ? std::cout << " is " << delta << " day(s) from now\n"
                                  : std::cout << " is today!\n";
    }
}

Possible output:

2020-11-15 was 1014 day(s) ago
2120-11-15 is 35510 day(s) from now
2023-08-26 is today!

The way this prints dates and does day-math is honestly iconic. 👑🌸

---

Later, bestie! 💖 Source/version/date sign-off vibes: http://cppreference.com, 2024.06.10, std::chrono...ay::operator(3). Periodt. 🎀🫶