How to Enable or Disable FMT_SAFE_DURATION_CAST in the fmt Library

Define FMT_SAFE_DURATION_CAST before including any fmt headers to enable compile-time safety checks for std::chrono::duration conversions, or define FMT_DISABLE_SAFE_DURATION_CAST to explicitly force the unsafe, faster default behavior.

The FMT_SAFE_DURATION_CAST macro controls whether the {fmt} library performs additional safety checks when casting between std::chrono::duration types. According to the fmtlib/fmt source code in include/fmt/chrono.h, this compile-time flag determines if fmt::detail::duration_cast validates representational compatibility between source and target duration types or falls back to the standard library's conversion.

What Is FMT_SAFE_DURATION_CAST?

FMT_SAFE_DURATION_CAST is a compile-time configuration macro that adds static assertions to duration casting operations within the formatting library. When enabled, the implementation performs a static_assert verifying that the source and target std::chrono::duration types have compatible representations, preventing inadvertent truncation or overflow during conversion.

The macro is consulted in include/fmt/chrono.h where the fmt::detail::duration_cast template function is implemented. The infrastructure for processing this macro is handled in include/fmt/compile.h, which manages the library's compile-time configuration options.

How to Enable FMT_SAFE_DURATION_CAST

To activate safe duration casting, you must define the macro in the global macro namespace before any fmt header is included. You can accomplish this via compiler flags or build system configuration.

Using Compiler Flags

Add the definition to your compiler command line when building translation units that include fmt headers:

g++ -DFMT_SAFE_DURATION_CAST -I/path/to/fmt/include main.cpp -lfmt -o my_app

Using CMake

In CMake-based projects, apply the definition to specific targets. The fmt library's CMakeLists.txt recognizes this option for CMake users, or you can set it manually:

target_compile_definitions(your_target PRIVATE FMT_SAFE_DURATION_CAST)

This ensures the macro is visible during compilation of all source files that include fmt/chrono.h.

How to Disable Safe Duration Cast

The library defaults to the unsafe, faster cast when FMT_SAFE_DURATION_CAST is undefined. However, you can explicitly disable the safety checks if your build environment requires it.

Explicit Disabling

Define FMT_DISABLE_SAFE_DURATION_CAST to force the unsafe conversion path regardless of other project settings:

g++ -DFMT_DISABLE_SAFE_DURATION_CAST main.cpp -lfmt -o my_app

Or in CMake:

target_compile_definitions(your_target PRIVATE FMT_DISABLE_SAFE_DURATION_CAST)

Default Behavior

When neither macro is defined, fmt::detail::duration_cast uses std::chrono::duration_cast directly without additional compile-time checks. This default prioritizes compilation speed and runtime performance over safety validation.

Implementation in fmt/chrono.h

The actual casting logic resides in include/fmt/chrono.h. When FMT_SAFE_DURATION_CAST is active, fmt::detail::duration_cast performs safety validation before performing the conversion. When disabled, the function immediately delegates to the standard library's casting mechanism without the extra static_assert checks.

Example usage showing the compile-time safety check:

#include <fmt/chrono.h>
#include <chrono>

int main() {
    std::chrono::seconds s{5};
    // With FMT_SAFE_DURATION_CAST enabled, this conversion is checked at compile time
    std::chrono::milliseconds ms = fmt::detail::duration_cast<std::chrono::milliseconds>(s);
    fmt::print("{}\n", ms);
}

Summary

• FMT_SAFE_DURATION_CAST enables compile-time safety checks for std::chrono::duration conversions in include/fmt/chrono.h.
• Enable via -DFMT_SAFE_DURATION_CAST compiler flag or CMake target_compile_definitions.
• Disable explicitly via FMT_DISABLE_SAFE_DURATION_CAST or rely on the unsafe default behavior.
• The safe mode uses static_assert to verify representational compatibility; the unsafe mode uses standard std::chrono::duration_cast.
• Applicable to fmt::detail::duration_cast operations when formatting chrono types.

Frequently Asked Questions

How do I check if FMT_SAFE_DURATION_CAST is enabled in my build?

Check your compiler definitions or inspect the macro state in source code using #ifdef FMT_SAFE_DURATION_CAST. The fmt library does not provide a runtime query mechanism for this compile-time configuration flag.

Does FMT_SAFE_DURATION_CAST affect runtime performance?

No. Because the checks are implemented as static_assert statements evaluated at compile time, enabled builds incur zero runtime overhead. The unsafe default is preferred only to minimize compile-time complexity or when integration with custom duration types requires standard casting behavior.

Can I enable safe duration casting for only specific translation units?

Yes. Since FMT_SAFE_DURATION_CAST is a preprocessor macro, you can define it per-source-file using local #define directives before including fmt/chrono.h, or apply compiler definitions selectively to specific CMake targets without affecting the entire project.

Where is the duration_cast function implemented?

The fmt::detail::duration_cast template function is defined in include/fmt/chrono.h within the fmtlib/fmt repository. The macro handling infrastructure that processes FMT_SAFE_DURATION_CAST is located in include/fmt/compile.h.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}