C++ Reference ยท Memory and Utilities
C++ chrono calendar types and time zones (C++20)
Reference for the C++20 chrono calendar: year_month_day, weekday, last, sys_days arithmetic, validity checks, zoned_time and the time zone database.
C++20 extended <chrono> with civil-calendar types. year, month and day are small value types; year_month_day combines them into a date; weekday and weekday_indexed describe "the second Tuesday"; year_month_day_last and the tag std::chrono::last express "the last day of the month". Dates can be converted to sys_days (a count of days since 1970-01-01) for arithmetic and back again.
Time zones (std::chrono::time_zone, zoned_time, current_zone(), locate_zone()) convert between UTC and local time using the IANA database. These need the database at run time, which a normal desktop or server provides.
using namespace std::chrono; year_month_day d = 2025y / March / 9; sys_days days_since_epoch = d; // convertible both ways
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
// Calendar types (all in std::chrono, C++20) class year; class month; class day; class weekday; class year_month_day; class year_month_day_last; class year_month_weekday; inline constexpr last_spec last{}; // Literals: 2025y, 9d; constants January ... December, Sunday ... Saturday // Time zones const time_zone* locate_zone(std::string_view name); const time_zone* current_zone(); template<class Duration, class TimeZonePtr = const time_zone*> class zoned_time;
| Name | Description |
|---|---|
year_month_day |
A date; year(), month(), day() accessors; ok() tells whether it exists. |
sys_days |
A time_point<system_clock, days>; convert a date to it for arithmetic. |
weekday |
Day of week; Friday[3] means the third Friday (weekday_indexed); Friday[last] the last. |
year_month_day_last |
Created with y / m / last; has day() returning the last valid day. |
hh_mm_ss |
Splits a duration into hours, minutes, seconds and fractions. |
zoned_time |
A moment together with a time zone; prints local time and offset. |
locate_zone(name) |
Looks up an IANA name such as "Europe/Berlin"; throws std::runtime_error if unknown. |
Returns: value types; ok() returns bool; locate_zone returns a pointer to a zone in the database.
Errors / undefined behavior: invalid dates are representable and not an error until you convert them: converting an invalid year_month_day to sys_days gives an unspecified result. locate_zone and the zoned_time constructor throw std::runtime_error for unknown names or an unavailable database. Ambiguous or nonexistent local times (around daylight-saving changes) throw nonexistent_local_time or ambiguous_local_time unless you choose how to resolve them.
Usage notes
- Check
ok()after month or year arithmetic.2025-01-31 + months{1}is2025-02-31, which does not exist. Either clamp to the month's last day as shown, or handle the failure. - Use
sys_daysfor day arithmetic and differences. Addingdays{n}to ayear_month_dayis not supported directly; convert first. - Several spellings, one type:
y / m / d,d / m / yandm / d / yall work, as long as at least one operand is a typed value such as2025yor9d. Plain integers fill the remaining slots. monthsandyearsare calendar-aware only when applied toyear_month_day,year_monthoryear. Added tosys_daysor atime_pointthey are average-length durations.- Time zones need the IANA database. GCC reads the system's tzdata (or its own copy); a minimal container image without it makes
locate_zonethrow. Programs should be ready for that. local_timeis not a moment.local_days,local_secondsandzoned_timeseparate "what the wall clock shows" from "which instant that is". Usezoned_timeto move between them.- Formatting:
std::format("{:%A %F %T %Z}", zt)andstd::cout << ztboth work with<chrono>and<format>; parsing usesstd::chrono::from_streamandstd::chrono::parse. - Version availability: calendar types and time zones are C++20. The GCC 15 runner used for the examples supports them, including zone names such as
Asia/Tokyo. - The limits of
yearare about plus or minus 32767; arithmetic outside that range is unspecified.