From a75e8af487d741a34380ae8bf2483954b14e6d1a Mon Sep 17 00:00:00 2001 From: Victor Zverovich Date: Sun, 31 Aug 2025 10:51:29 -0700 Subject: [PATCH] Update docs --- doc/api.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/doc/api.md b/doc/api.md index cb4b379a..a4549579 100644 --- a/doc/api.md +++ b/doc/api.md @@ -549,14 +549,14 @@ fmt::print("{}", +s.bit); This is a known limitation of "perfect" forwarding in C++. -## Format String Compilation +## Compile-Time Support `fmt/compile.h` provides format string compilation and compile-time (`constexpr`) formatting enabled via the `FMT_COMPILE` macro or the `_cf` user-defined literal defined in namespace `fmt::literals`. Format strings marked with `FMT_COMPILE` or `_cf` are parsed, checked and converted into efficient formatting code at compile-time. This supports arguments of built-in -and string types as well as user-defined types with `format` functions taking +and string types as well as user-defined types with `format` methods taking the format context type as a template parameter in their `formatter` specializations. For example: @@ -571,6 +571,29 @@ Format string compilation can generate more binary code compared to the default API and is only recommended in places where formatting is a performance bottleneck. +The same API supports formatting at compile time e.g. in `constexpr` functions. +It works with built-in and user-defined formatters that have `constexpr` `parse` +and `format` methods. Example ([run](https://www.godbolt.org/z/rzY8Tcjf8)): + + struct point { + double x; + double y; + }; + + template <> struct fmt::formatter { + constexpr auto parse(format_parse_context& ctx) { + return ctx.begin(); + } + + template + constexpr auto format(const point& p, FormatContext& ctx) const { + return format_to(ctx.out(), "({}, {})"_cf, p.x, p.y); + } + }; + + using namespace fmt::literals; + constexpr std::string s = fmt::format("{}"_cf, point(1, 2)); + ::: FMT_COMPILE ::: operator""_cf