Chrono
Curated hub for durations, clocks, time points, calendars, time zones, formatting/parsing, literals, and C compatibility.
The chrono library spans several distinct models: measuring elapsed time, representing absolute points in time, formatting and parsing, calendar arithmetic, time-zone-aware civil time, and compatibility with the older C date/time surface. This page is the task-first entry point for choosing the right chrono area before diving into individual types or functions.
# Start Here
Durations and units
Use durations when you are measuring or transforming spans of time rather than anchoring events to an absolute clock.
duration · duration_values · treat_as_floating_point · <chrono>
Time points and clocks
Use time points and clocks for timestamps, elapsed-time measurement, and conversions between time representations.
time_point · steady_clock · system_clock · high_resolution_clock
Calendars and civil dates
Use the calendar layer when the problem is calendar arithmetic, weekdays, months, and human-facing dates rather than raw epoch counts.
year · month · day · year_month_day
Time zones and local time
Start here for local-time conversion, time-zone databases, daylight-saving ambiguity, and zoned timestamps.
zoned_time · time_zone · current_zone · tzdb
Formatting and parsing
Use these routes when text representation matters: parsing timestamps, streaming chrono values, or formatting calendar/time-zone-aware data.
C compatibility
Use the C bridge when you need the older C date/time surface or must interoperate with `time_t` and C-style calendar APIs.
# Quick Map
| If you need to... | Start with | Why |
|---|---|---|
| Measure elapsed time or attach units to a count | duration | Durations model spans of time independently of any particular clock or epoch. |
| Timestamp an event on a specific clock | time_point, system_clock, steady_clock | Time points combine a duration-like offset with a clock model. |
| Pick the right clock for performance or wall time | steady_clock, system_clock, high_resolution_clock | `steady_clock` is monotonic for interval measurement; `system_clock` is the wall-clock route; `high_resolution_clock` is implementation-defined. |
| Represent calendar dates like 2026-02-28 or weekdays/months | year_month_day, weekday, month_day | The calendar layer is distinct from raw elapsed durations and epoch counts. |
| Convert between UTC, local, and named time zones | zoned_time, time_zone, current_zone | This route handles civil-time ambiguity, daylight-saving transitions, and the time-zone database. |
| Parse or format chrono values as text | parse, hh_mm_ss, chrono streaming/formatter pages | Use the text route when representation matters more than arithmetic. |
| Bridge to C date/time APIs | C date and time utilities, to_time_t, from_time_t | This is the interoperability route when modern chrono meets older `time_t`-based code. |
# Chrono Families
| Family | Representative entry points | Use it for |
|---|---|---|
| Durations and literals | duration, <chrono>, duration_values, treat_as_floating_point | Spans of time, unit-safe arithmetic, and source-level literal notation. |
| Clock and timestamp core | time_point, system_clock, steady_clock, high_resolution_clock | Timestamping, elapsed-time measurement, and conversions relative to clock epochs. |
| Calendar dates and civil time | year, month, day, year_month_day, weekday | Human-facing dates, weekdays, month/day composition, and calendar arithmetic. |
| Time zones and database | zoned_time, time_zone, tzdb, tzdb_list, current_zone | Local time conversion, named zones, database lookup/reload, and DST ambiguity handling. |
| Alternative clocks and conversions | utc_clock, tai_clock, gps_clock, file_clock, clock_cast | Cross-domain time models beyond the three classic clocks. |
| Formatting, parsing, and decomposition | parse, hh_mm_ss, from_stream | Text I/O and breaking down time values into display-friendly structures. |
# Clocks And Time Models
| Model | Use it when | Primary destinations |
|---|---|---|
| Monotonic elapsed time | You are measuring intervals and must not be affected by wall-clock adjustments. | steady_clock, time_point |
| System wall clock | You need real-world timestamps and conversion to/from `time_t` or calendar representations. | system_clock, to_time_t, from_time_t |
| Implementation-defined highest resolution | You want the implementation's finest exposed resolution and understand that it may alias another clock. | high_resolution_clock |
| Civil date/time | You are working with dates, weekdays, month/year composition, or user-facing calendar logic. | year_month_day, year_month_weekday, month_day |
| Zoned/local time | You need named time zones, local-time conversions, or DST-aware behavior. | zoned_time, time_zone, local_info, nonexistent_local_time, ambiguous_local_time |
# Standard Evolution
| Standard | What changed navigation-wise |
|---|---|
| C++11 | The original chrono model introduced durations, time_point, and the classic clocks as the core timing abstraction. |
| C++17 | Rounding and constexpr improvements made the duration/time_point core more practical for generic and compile-time-oriented code. |
| C++20 | The library expanded dramatically with calendars, time zones, parsing/formatting, and richer civil-time types, which changed chrono from a timing utility into a full date/time system. |
| C++26 | Hashing support for chrono value classes further broadens the library's use in associative/data-structure contexts. |
# Boundary Lines
| This hub covers | Use a different hub for |
|---|---|
| Durations, clocks, time points, calendars, time zones, chrono parsing/formatting, and C date/time compatibility. | Thread support when the main question is sleeping/waiting/concurrency primitives, I/O for broader stream architecture, and Numerics for non-time numeric computation. |
| The C++ chrono surface. | C chrono when you need the C library's date/time entry points instead of the C++ chrono model. |