C++20 std::format 替换 fmtlib 的关键点

进入 C++ 标准的库，实践时日往往很久，像 fmtlib、range-v3 这些经典库，都已存在十年以上。不受标准牢笼，一个库的发展会快速许多，是以其本身的功能要比加入标准的完善很多。例如 fmtlib，它比 std::format 使用起来更加方便，能直接支持 Formatting Ranges、Formatted Output、Terminal Color 等诸多功能，而这些功能要完全加入标准，可能得等到 C++29 了。

我在某个 C++20 库的开发中就需要使用 format，当时想着 fmtlib 功能更加完善，便没有直接使用 std::format。但后来就遇到了问题，首先是 fmtlib 有诸多版本，版本之间可能存在细微差异，用户也许并不像我们这般熟悉 C++，编译之时，问题千奇百怪；其次是在用户机器上可能会出现一些莫名其妙的问题，而这些问题放到自己的机器上却顿时匿迹，分析起来将花费大量时间；最后是编译错误信息，fmtlib 开发之时，Concepts 还未进标准，而其采用的定制方式是模板特化，稍微出现一点问题便会弹出满屏的模板错误，而这些错误信息和真实错误毫不相关，加大了定位问题的难度。

总而言之，fmtlib 隐藏的坑不小，换成 std::format 能够避免很多细微的隐患，减少普通用户的抱怨之声。然而，std::format 缺少很多 fmtlib 直接具备的功能，替换也并非那么简单，本篇讲解的就是这些替换的细节。

下面分成三部分关键点进行讨论。

第一，运行期定制。

std::formatter 默认只支持编译期定制，在 fmtlib 中存在 fmt::runtime 可以编写运行期的定制。比如，下面是一个使用 fmtlib 定制 response 的例子：

template <>
struct fmt::formatter<mylib::response> {
    constexpr auto parse(format_parse_context& ctx) {
        auto it = ctx.begin(), end = ctx.end();
        if (it != end && *it == 'r') it++;
        if (it != end && *it != '}') throw fmt::format_error("invalid response format");
        return it;
    }

    template <typename FormatContext>
    auto format(const mylib::response& r, FormatContext& ctx) {
        int index = 1;
        std::string info;
        for (const auto& item : r.data())
        {
            info += fmt::format("[{:>{}}] ", index++, std::to_string(r.size()).length());
            for (auto it = item.begin(); it != item.end(); ++it)
            {
                info += fmt::format("{}: {} ", it.key(), it.value().template get<std::string>());
            }

            info += "\n";
        }

        return fmt::format_to(ctx.out(), fmt::runtime(info));
    }
};

response 特化就是将内部数据格式化到 info 中，细节不论，由于 info 是运行期的，必须使用 fmt::runtime(info) 才能保证正常编译。

std::runtime_format C++26 才入标准，当前使用 std::format 的替换方式如下：

template <>
struct std::formatter<mylib::response> {
    constexpr auto parse(format_parse_context& ctx) {
        auto it = ctx.begin(), end = ctx.end();
        if (it != end && *it == 'r') it++;
        if (it != end && *it != '}') throw std::format_error("invalid response format");
        return it;
    }

    template <typename FormatContext>
    auto format(const mylib::response& r, FormatContext& ctx) const {
        int index = 1;
        std::string info;
        for (const auto& item : r.data())
        {
            info += std::vformat("[{:>{}}] ", std::make_format_args(
                mylib::unmove(index++), mylib::unmove(std::to_string(r.size()).length())));
            for (auto it = item.begin(); it != item.end(); ++it)
            {
                info += std::vformat("{}: {} ", std::make_format_args(
                    it.key(), mylib::unmove(it.value().template get<std::string>())));
            }

            info += "\n";
        }

        return std::vformat_to(ctx.out(), "{}", std::make_format_args(info));
    }
};

关键点有三个，一是使用 std::vformat 而不是 std::format，后者不支持运行期；二是 std::vformat 不能直接传递参数，需要借助 std::make_format_args；三是 std::make_format_args 不支持右值，必须传递左值。

对于第三点，解决办法是编写一个 unmove 函数，将右值转换为左值。实现如下：

namespace mylib {

template <typename T>
auto unmove(T&& x) -> const T& {
    return x;
}

} // namespace mylib

其中，还有一个非常重要的点，auto format() const 成员函数必须要有 const 修饰，少了便会产生满屏的模板错误。

同样在返回结果时，也需要使用 std::vformat_to()，而不是 std::format_to()。

第二，Formatted output。

C++23 才支持 std::print，而 fmt::print 在低版本也可以直接使用。因此，为了保证这种语法的一致性，也为了隐藏这种 print 细节，可以自己封装一个 print()。实现如下：

namespace mylib {

template <typename... Args>
inline auto format(std::format_string<Args...>&& fmt, Args&&... args)
    -> std::string {
    return std::format(std::forward<std::format_string<Args...>>(fmt), std::forward<Args>(args)...);
}

template <typename... Args>
inline auto print(std::format_string<Args...>&& fmt, Args&&... args)
    -> void {
    std::cout << mylib::format(std::forward<std::format_string<Args...>>(fmt), std::forward<Args>(args)...);
}

} // namespace mylib

建议将 format() 和 print() 一起封装，让用户直接使用 mylib::format 和 mylib::print，避免他们直接接触 std::format，为后续代码更新和优化留出空间。

这里的语法和 fmtlib 基本一致，只需注意采用 std::format_string 转发格式化字符串。

第三点，Terminal Color。

fmtlib 的这个功能允许控制命令行输出内容的颜色，在基于 format 编写一些简易的日志模块时，这个功能有利于控制不同日志等级的显示颜色。

fmtlib 含有一个 fmt/color.h 定义颜色相关的功能，下面是一个使用例子：

fmt::print(fg(fmt::color::gray), "{}s", mylib::now::seconds);

这将输出灰色的内容，而 std::format 是缺少这个模块的，我们需要自己定义该部分功能。

怎么定义呢？下面是完整实现：

namespace mylib {

    enum class color : uint32_t {
        alice_blue = 0xF0F8FF,               // rgb(240,248,255)
        antique_white = 0xFAEBD7,            // rgb(250,235,215)
        aqua = 0x00FFFF,                     // rgb(0,255,255)
        aquamarine = 0x7FFFD4,               // rgb(127,255,212)
        azure = 0xF0FFFF,                    // rgb(240,255,255)
        beige = 0xF5F5DC,                    // rgb(245,245,220)
        bisque = 0xFFE4C4,                   // rgb(255,228,196)
        black = 0x000000,                    // rgb(0,0,0)
        blanched_almond = 0xFFEBCD,          // rgb(255,235,205)
        blue = 0x0000FF,                     // rgb(0,0,255)
        blue_violet = 0x8A2BE2,              // rgb(138,43,226)
        brown = 0xA52A2A,                    // rgb(165,42,42)
        burly_wood = 0xDEB887,               // rgb(222,184,135)
        cadet_blue = 0x5F9EA0,               // rgb(95,158,160)
        chartreuse = 0x7FFF00,               // rgb(127,255,0)
        chocolate = 0xD2691E,                // rgb(210,105,30)
        coral = 0xFF7F50,                    // rgb(255,127,80)
        cornflower_blue = 0x6495ED,          // rgb(100,149,237)
        cornsilk = 0xFFF8DC,                 // rgb(255,248,220)
        crimson = 0xDC143C,                  // rgb(220,20,60)
        cyan = 0x00FFFF,                     // rgb(0,255,255)
        dark_blue = 0x00008B,                // rgb(0,0,139)
        dark_cyan = 0x008B8B,                // rgb(0,139,139)
        dark_golden_rod = 0xB8860B,          // rgb(184,134,11)
        dark_gray = 0xA9A9A9,                // rgb(169,169,169)
        dark_green = 0x006400,               // rgb(0,100,0)
        dark_khaki = 0xBDB76B,               // rgb(189,183,107)
        dark_magenta = 0x8B008B,             // rgb(139,0,139)
        dark_olive_green = 0x556B2F,         // rgb(85,107,47)
        dark_orange = 0xFF8C00,              // rgb(255,140,0)
        dark_orchid = 0x9932CC,              // rgb(153,50,204)
        dark_red = 0x8B0000,                 // rgb(139,0,0)
        dark_salmon = 0xE9967A,              // rgb(233,150,122)
        dark_sea_green = 0x8FBC8F,           // rgb(143,188,143)
        dark_slate_blue = 0x483D8B,          // rgb(72,61,139)
        dark_slate_gray = 0x2F4F4F,          // rgb(47,79,79)
        dark_turquoise = 0x00CED1,           // rgb(0,206,209)
        dark_violet = 0x9400D3,              // rgb(148,0,211)
        deep_pink = 0xFF1493,                // rgb(255,20,147)
        deep_sky_blue = 0x00BFFF,            // rgb(0,191,255)
        dim_gray = 0x696969,                 // rgb(105,105,105)
        dodger_blue = 0x1E90FF,              // rgb(30,144,255)
        fire_brick = 0xB22222,               // rgb(178,34,34)
        floral_white = 0xFFFAF0,             // rgb(255,250,240)
        forest_green = 0x228B22,             // rgb(34,139,34)
        fuchsia = 0xFF00FF,                  // rgb(255,0,255)
        gainsboro = 0xDCDCDC,                // rgb(220,220,220)
        ghost_white = 0xF8F8FF,              // rgb(248,248,255)
        gold = 0xFFD700,                     // rgb(255,215,0)
        golden_rod = 0xDAA520,               // rgb(218,165,32)
        gray = 0x808080,                     // rgb(128,128,128)
        green = 0x008000,                    // rgb(0,128,0)
        green_yellow = 0xADFF2F,             // rgb(173,255,47)
        honey_dew = 0xF0FFF0,                // rgb(240,255,240)
        hot_pink = 0xFF69B4,                 // rgb(255,105,180)
        indian_red = 0xCD5C5C,               // rgb(205,92,92)
        indigo = 0x4B0082,                   // rgb(75,0,130)
        ivory = 0xFFFFF0,                    // rgb(255,255,240)
        khaki = 0xF0E68C,                    // rgb(240,230,140)
        lavender = 0xE6E6FA,                 // rgb(230,230,250)
        lavender_blush = 0xFFF0F5,           // rgb(255,240,245)
        lawn_green = 0x7CFC00,               // rgb(124,252,0)
        lemon_chiffon = 0xFFFACD,            // rgb(255,250,205)
        light_blue = 0xADD8E6,               // rgb(173,216,230)
        light_coral = 0xF08080,              // rgb(240,128,128)
        light_cyan = 0xE0FFFF,               // rgb(224,255,255)
        light_golden_rod_yellow = 0xFAFAD2,  // rgb(250,250,210)
        light_gray = 0xD3D3D3,               // rgb(211,211,211)
        light_green = 0x90EE90,              // rgb(144,238,144)
        light_pink = 0xFFB6C1,               // rgb(255,182,193)
        light_salmon = 0xFFA07A,             // rgb(255,160,122)
        light_sea_green = 0x20B2AA,          // rgb(32,178,170)
        light_sky_blue = 0x87CEFA,           // rgb(135,206,250)
        light_slate_gray = 0x778899,         // rgb(119,136,153)
        light_steel_blue = 0xB0C4DE,         // rgb(176,196,222)
        light_yellow = 0xFFFFE0,             // rgb(255,255,224)
        lime = 0x00FF00,                     // rgb(0,255,0)
        lime_green = 0x32CD32,               // rgb(50,205,50)
        linen = 0xFAF0E6,                    // rgb(250,240,230)
        magenta = 0xFF00FF,                  // rgb(255,0,255)
        maroon = 0x800000,                   // rgb(128,0,0)
        medium_aquamarine = 0x66CDAA,        // rgb(102,205,170)
        medium_blue = 0x0000CD,              // rgb(0,0,205)
        medium_orchid = 0xBA55D3,            // rgb(186,85,211)
        medium_purple = 0x9370DB,            // rgb(147,112,219)
        medium_sea_green = 0x3CB371,         // rgb(60,179,113)
        medium_slate_blue = 0x7B68EE,        // rgb(123,104,238)
        medium_spring_green = 0x00FA9A,      // rgb(0,250,154)
        medium_turquoise = 0x48D1CC,         // rgb(72,209,204)
        medium_violet_red = 0xC71585,        // rgb(199,21,133)
        midnight_blue = 0x191970,            // rgb(25,25,112)
        mint_cream = 0xF5FFFA,               // rgb(245,255,250)
        misty_rose = 0xFFE4E1,               // rgb(255,228,225)
        moccasin = 0xFFE4B5,                 // rgb(255,228,181)
        navajo_white = 0xFFDEAD,             // rgb(255,222,173)
        navy = 0x000080,                     // rgb(0,0,128)
        old_lace = 0xFDF5E6,                 // rgb(253,245,230)
        olive = 0x808000,                    // rgb(128,128,0)
        olive_drab = 0x6B8E23,               // rgb(107,142,35)
        orange = 0xFFA500,                   // rgb(255,165,0)
        orange_red = 0xFF4500,               // rgb(255,69,0)
        orchid = 0xDA70D6,                   // rgb(218,112,214)
        pale_golden_rod = 0xEEE8AA,          // rgb(238,232,170)
        pale_green = 0x98FB98,               // rgb(152,251,152)
        pale_turquoise = 0xAFEEEE,           // rgb(175,238,238)
        pale_violet_red = 0xDB7093,          // rgb(219,112,147)
        papaya_whip = 0xFFEFD5,              // rgb(255,239,213)
        peach_puff = 0xFFDAB9,               // rgb(255,218,185)
        peru = 0xCD853F,                     // rgb(205,133,63)
        pink = 0xFFC0CB,                     // rgb(255,192,203)
        plum = 0xDDA0DD,                     // rgb(221,160,221)
        powder_blue = 0xB0E0E6,              // rgb(176,224,230)
        purple = 0x800080,                   // rgb(128,0,128)
        rebecca_purple = 0x663399,           // rgb(102,51,153)
        red = 0xFF0000,                      // rgb(255,0,0)
        rosy_brown = 0xBC8F8F,               // rgb(188,143,143)
        royal_blue = 0x4169E1,               // rgb(65,105,225)
        saddle_brown = 0x8B4513,             // rgb(139,69,19)
        salmon = 0xFA8072,                   // rgb(250,128,114)
        sandy_brown = 0xF4A460,              // rgb(244,164,96)
        sea_green = 0x2E8B57,                // rgb(46,139,87)
        sea_shell = 0xFFF5EE,                // rgb(255,245,238)
        sienna = 0xA0522D,                   // rgb(160,82,45)
        silver = 0xC0C0C0,                   // rgb(192,192,192)
        sky_blue = 0x87CEEB,                 // rgb(135,206,235)
        slate_blue = 0x6A5ACD,               // rgb(106,90,205)
        slate_gray = 0x708090,               // rgb(112,128,144)
        snow = 0xFFFAFA,                     // rgb(255,250,250)
        spring_green = 0x00FF7F,             // rgb(0,255,127)
        steel_blue = 0x4682B4,               // rgb(70,130,180)
        tan = 0xD2B48C,                      // rgb(210,180,140)
        teal = 0x008080,                     // rgb(0,128,128)
        thistle = 0xD8BFD8,                  // rgb(216,191,216)
        tomato = 0xFF6347,                   // rgb(255,99,71)
        turquoise = 0x40E0D0,                // rgb(64,224,208)
        violet = 0xEE82EE,                   // rgb(238,130,238)
        wheat = 0xF5DEB3,                    // rgb(245,222,179)
        white = 0xFFFFFF,                    // rgb(255,255,255)
        white_smoke = 0xF5F5F5,              // rgb(245,245,245)
        yellow = 0xFFFF00,                   // rgb(255,255,0)
        yellow_green = 0x9ACD32,             // rgb(154,205,50)
        debug = 0xCC8BF5,                    // rgb(204,139,245)
        info = 0x77F9F6,                     // rgb(119,249,246)
        warning = 0xFCF669,                  // rgb(252,246,105)
        success = 0x84FD61,                  // rgb(132,253,97)
        error = 0xE96A63,                    // rgb(233,106,99)
    };

    inline auto rgb(color c) -> std::tuple<int, int, int> {
        auto value = static_cast<uint32_t>(c);
        int r = (value >> 16) & 0xFF;
        int g = (value >> 8) & 0xFF;
        int b = value & 0xFF;
        return std::make_tuple(r, g, b);
    }

    inline auto fg(color c) -> std::string {
        auto [r, g, b] = rgb(c);
        return std::format("\033[38;2;{};{};{}m", r, g, b);
    }

    inline constexpr auto end_color() {
        return "\033[0m";
    }

} // namespace mylib

颜色定义完成之后，可以再重载一个支持指定颜色的 print()，作为中间层，简化语法。代码：

inline auto print(mylib::color c, std::string_view content) -> void {
    std::cout << fg(c) << content << end_color();
}

于是，fmtlib 的等价写法，可写为：

print(mylib::color::gray, std::format("{}s", mylib::now::seconds()));

当掌握这些关键点之后，std::format 的灵活性将极大增强，完全可以替换 fmtlib 中常用的功能。