Skip to content
Tutorials Center
My learning

Topics

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.

C++
using namespace std::chrono;
year_month_day d = 2025y / March / 9;
sys_days days_since_epoch = d;     // convertible both ways

Try it

C++ Building and checking dates

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.

C++ Time zones with zoned_time

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

C++
// 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} is 2025-02-31, which does not exist. Either clamp to the month's last day as shown, or handle the failure.
  • Use sys_days for day arithmetic and differences. Adding days{n} to a year_month_day is not supported directly; convert first.
  • Several spellings, one type: y / m / d, d / m / y and m / d / y all work, as long as at least one operand is a typed value such as 2025y or 9d. Plain integers fill the remaining slots.
  • months and years are calendar-aware only when applied to year_month_day, year_month or year. Added to sys_days or a time_point they 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_zone throw. Programs should be ready for that.
  • local_time is not a moment. local_days, local_seconds and zoned_time separate "what the wall clock shows" from "which instant that is". Use zoned_time to move between them.
  • Formatting: std::format("{:%A %F %T %Z}", zt) and std::cout << zt both work with <chrono> and <format>; parsing uses std::chrono::from_stream and std::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 year are about plus or minus 32767; arithmetic outside that range is unspecified.