diff --git a/doc/api.md b/doc/api.md index a4549579..1d59281d 100644 --- a/doc/api.md +++ b/doc/api.md @@ -560,30 +560,36 @@ 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: - template <> struct fmt::formatter { - constexpr auto parse(format_parse_context& ctx); - - template - auto format(const point& p, FormatContext& ctx) const; - }; - -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(); + constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); } + + template + auto format(const point& p, FormatContext& ctx) const { + return format_to(ctx.out(), "({}, {})"_cf, p.x, p.y); } + }; + + using namespace fmt::literals; + std::string s = fmt::format("{}"_cf, point(4, 2)); + +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 APIs support formatting at compile time e.g. in `constexpr` +and `consteval` functions. Additionally there is an experimental +`FMT_STATIC_FORMAT` that allows formatting into a string of the exact +required size at compile time. Compile-time formatting works with built-in +and user-defined formatters that have `constexpr` `format` methods. +Example: + + template <> struct fmt::formatter { + constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); } template constexpr auto format(const point& p, FormatContext& ctx) const { @@ -591,12 +597,14 @@ and `format` methods. Example ([run](https://www.godbolt.org/z/rzY8Tcjf8)): } }; - using namespace fmt::literals; - constexpr std::string s = fmt::format("{}"_cf, point(1, 2)); + constexpr auto s = FMT_STATIC_FORMAT("{}", point(4, 2)); + const char* cstr = s.c_str(); // Points the static string "(4, 2)". + +::: operator""_cf ::: FMT_COMPILE -::: operator""_cf +::: FMT_STATIC_FORMAT ## Terminal Colors and Text Styles