# How fmtlib Supports Chrono Time Formatting: A Complete Guide to C++ Date & Time Output > Learn how fmtlib enhances C++ chrono time formatting. Discover locale-aware output, C++20 calendar support, and thread-safe conversions via `` for `time_point` and `duration`. - Repository: [Hello World Foundation/fmt](https://github.com/fmtlib/fmt) - Tags: deep-dive - Published: 2026-09-08 --- **{fmt} enables comprehensive chrono time formatting through the `` header, providing `formatter` specializations for `std::chrono::time_point` and `std::chrono::duration` that support `std::put_time`-compatible specifiers, locale-aware output, and C++20 calendar types with thread-safe conversions.** The {fmt} library extends its high-performance formatting capabilities to C++11 and C++20 chrono types through dedicated implementations in [`include/fmt/chrono.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/chrono.h). By specializing the `formatter` template for temporal types, fmtlib eliminates the need for manual `std::tm` conversions while providing compile-time checking of format strings. This architecture supports everything from simple timestamp output to ISO week dates and sub-second precision with full thread safety. ## Architecture of fmtlib Chrono Time Formatting ### Type Detection via Formatter Specializations The foundation of chrono support rests on explicit template specializations defined at lines **2036–2057** of [`include/fmt/chrono.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/chrono.h). These specializations target `std::chrono::duration` for time intervals and `std::chrono::time_point` for absolute timestamps. When you pass a chrono object to `fmt::format` or `fmt::print`, the compiler selects these overloads over the generic formatter base class, enabling type-specific parsing and validation. ### Format Specifier Parsing Format strings are processed by `parse_chrono_format`, implemented at lines **628–672** according to the fmtlib source code. This function recognizes standard `std::put_time` specifiers including `%Y` (year), `%m` (month), `%d` (day), `%H` (hour), `%M` (minute), and `%S` (second). It also handles locale-aware extensions (`%E…` and `%O…`) and precision modifiers for fractional seconds. The parser operates at compile time when using C++20 `std::format` compatibility or `FMT_STRING` macros, catching invalid specifiers before runtime. ### Safe Time Conversions For calendar-based formatting, fmtlib converts time points to `std::tm` structures using the thread-safe `gmtime` helper (lines **949–961**). The implementation handles `sys_time` conversions through a protected `duration_cast` chain (lines **818–842**) that prevents overflow during unit conversions. Additionally, the `safe_duration_cast` facility (lines **33–120**) guards against arithmetic overflow and underflow when converting between duration types, unless explicitly disabled by defining `FMT_SAFE_DURATION_CAST`. ## Advanced Formatting Features ### The tm_writer Implementation Starting at line **1342** in [`include/fmt/chrono.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/chrono.h), the `tm_writer` class orchestrates the actual output generation. This class writes individual temporal components according to parsed specifiers, handling padding requirements, alternative numeric representations, ISO week date calculations, and timezone offsets. The `tm_writer` works in conjunction with [`include/fmt/ostream.h`](https://github.com/fmtlib/fmt/blob/main/include/fmt/ostream.h) to provide locale-aware output through `std::time_put` integration, supporting non-ASCII characters and regional date formats. ### Handling Sub-Second Precision For durations and time points with fractional components, fmtlib employs `write_fractional_seconds` (lines **665–714**) and `write_floating_seconds` (lines **716–744**). These functions emit fractional parts with the correct number of digits, respecting C++20 "fractional-digit" formatting rules. You can control precision using width modifiers like `%3f` for milliseconds or `%9f` for nanoseconds, with the library automatically truncating or zero-padding as needed. ### C++20 Calendar Type Support The implementation conditionally supports C++20 calendar types such as `std::chrono::year_month_day` and `std::chrono::weekday` via `__cpp_lib_chrono` feature test macros (lines **226–242**). When compiled with C++20 support, the same formatting interface works seamlessly with these types without requiring additional headers. The `formatter` specialization (lines **2036–2094**) dispatches to specialized handlers that understand calendar arithmetic, enabling direct formatting of dates without converting to `time_point` first. ## Practical Examples of fmtlib Chrono Time Formatting ```cpp #include #include #include int main() { using namespace std::chrono; // 1. Simple time_point formatting (default locale) auto now = system_clock::now(); fmt::print("Now: {:%Y-%m-%d %H:%M:%S}\n", now); // → Now: 2024-04-18 12:34:56 // 2. Sub‑second precision (default is full precision) fmt::print("Now (ms): {:%Y-%m-%d %H:%M:%S.%3f}\n", now); // → Now (ms): 2024-04-18 12:34:56.123 // 3. ISO week date and weekday name fmt::print("ISO week: {:%G-W%V-%u (%A)}\n", now); // → ISO week: 2024-W16-4 (Thursday) // 4. Using a custom locale (e.g. German) std::locale german("de_DE.UTF-8"); fmt::print(german, "German date: {:%x}\n", now); // → German date: 18.04.2024 // 5. Formatting a duration directly auto dur = milliseconds(12345); fmt::print("Duration: {:%H:%M:%S.%f}\n", dur); // → Duration: 00:00:12.345 } ``` ## Summary - **Include ``** to enable chrono formatting capabilities beyond the core library - **Formatter specializations** at lines 2036–2057 automatically handle `time_point` and `duration` types via template metaprogramming - **`parse_chrono_format`** (lines 628–672) supports standard `std::put_time` specifiers plus locale extensions and precision controls - **Thread-safe conversions** use `gmtime` helpers (lines 949–961) and protected duration casting (lines 818–842) to prevent overflow - **Sub-second precision** is handled by `write_fractional_seconds` (lines 665–714) with configurable width specifiers - **C++20 support** activates automatically via `__cpp_lib_chrono` checks (lines 226–242) for calendar types like `year_month_day` ## Frequently Asked Questions ### How do I format a std::chrono::system_clock::time_point using fmtlib? Include `` and pass the time point to `fmt::format` with chrono-specific format specifiers. For example, `fmt::format("{:%Y-%m-%d %H:%M:%S}", now)` produces an ISO-like timestamp string. The library automatically detects the type through the `formatter` specialization at lines 2036–2057 and handles the conversion to `std::tm` using the thread-safe `gmtime` implementation. ### What format specifiers are supported for chrono types in fmt? fmtlib supports all standard `std::put_time` specifiers including `%Y` (year), `%m` (month), `%d` (day), `%H` (24-hour), `%I` (12-hour), `%M` (minute), `%S` (second), `%A` (weekday name), `%z` (timezone offset), and `%Z` (timezone name). It also supports precision modifiers like `%3f` for milliseconds. The `parse_chrono_format` function at lines 628–672 implements this parsing logic with compile-time validation. ### Does fmtlib support C++20 calendar types like year_month_day? Yes. When compiled with C++20 support, fmtlib detects `__cpp_lib_chrono` at lines 226–242 and extends formatting capabilities to `std::chrono::year_month_day`, `std::chrono::weekday`, and other calendar types. These types use the same formatting interface as `time_point`, with the `tm_writer` class handling the specific field extraction required for calendar arithmetic without manual conversion. ### How does fmtlib handle time zone conversions when formatting chrono types? The library provides the `gmtime` function (lines 949–961) for converting `sys_time` to `std::tm` in UTC. For local time conversions, it relies on system `localtime` facilities through the `tm_writer` class. The formatting specifiers `%z` and `%Z` output timezone offset and name respectively, though you should ensure the `time_point` represents the desired timezone before formatting, as fmtlib does not implicitly convert between timezones during formatting operations.