{fmt} 库 API 完全指南从基础格式化到 C20 兼容与二进制优化【免费下载链接】fmtA modern formatting library项目地址: https://gitcode.com/GitHub_Trending/fm/fmt导读本文是 {fmt} 现代 C 格式化库的 API 权威参考系统梳理了fmt/base.h基础 API、fmt/format.h完整格式化 API以及 ranges、chrono、std、enum、compile、color、os、ostream、args、printf、xchar 等十余个功能头文件的核心接口与用法。你将掌握格式化字符串语法、用户自定义类型的两种扩展方式、编译期检查与类型擦除、命名参数、动态参数列表、宽字符支持以及通过 CMake 选项与预处理器宏裁剪库体积的完整配置方案。文中所有结论均以当前仓库源码为据可放心用于工程实践。{fmt} 的 API 由以下组件构成均位于include/fmt/目录fmt/base.h基础 API提供char/UTF-8 的主要格式化函数带 C20 编译期检查依赖最少fmt/format.hfmt::format等完整格式化函数及 locale 支持fmt/ranges.hrange 与 tuple 的格式化fmt/chrono.h日期时间格式化fmt/std.h标准库类型的 formatterfmt/enum.h注解枚举的格式化fmt/compile.h格式字符串编译编译期格式化fmt/color.h终端颜色与文本样式fmt/os.h系统 API文件输出、Windows 错误fmt/ostream.hstd::ostream支持fmt/args.h动态参数列表fmt/printf.h类型安全的printffmt/xchar.h可选的wchar_t支持。所有函数与类型都位于命名空间fmt中所有宏都以FMT_为前缀。C Module API如果使用 C 模块module方式构建 {fmt}则无需逐个 include 上述头文件直接用一条import fmt;语句即可。除此之外下文列出的所有功能保持不变。从仓库的CMakeLists.txt可以看出{fmt} 同时维护了传统的头文件/静态库构建与模块构建路径模块方式在优化构建下可将应用代码编译时间降低约 27%详见 README.md 中的编译时间对比表。基础 APIfmt/base.hfmt/base.h定义基础 API为char/UTF-8 提供主要格式化函数并带 C20 编译期检查。该头文件包含依赖极少利于缩短编译时间。需要注意只有在以库方式默认方式使用 {fmt} 时单独包含fmt/base.h才有收益在 header-only 模式下并不明显。fmt/base.h为以下类型提供了内置的formatter特化int、long longunsigned、unsigned long longfloat、double、long doubleboolcharconst char*、fmt::string_viewconst void*这些函数使用的格式字符串语法与 Python 的str.format类似接受fmt和args两个参数fmt是包含字面文本与花括号{}包围的替换字段的格式字符串字段会被替换为格式化后的参数。fmt::format_string是一种可从字符串字面量或constexpr字符串隐式构造、并在 C20 下编译期检查的格式字符串类型若要传入运行时格式字符串需要用fmt::runtime包裹args是要被格式化的对象列表。I/O 错误除非另行说明以std::system_error异常的形式上报。基础 API 的核心函数包括print(format_stringT..., T...)向标准输出打印print(FILE*, format_stringT..., T...)向指定FILE*打印println(format_stringT..., T...)与println(FILE*, ...)带换行的打印format_to(OutputIt, format_stringT..., T...)格式化为迭代器输出format_to_n(OutputIt, size_t, format_stringT..., T...)限定最大输出长度的格式化返回format_to_n_result包含迭代器与写入字符数formatted_size(format_stringT..., T...)返回格式化结果的字符数不实际输出。在README.md的入门示例中仅包含fmt/base.h即可完成fmt::print(Hello, world!\n)而fmt::format(The answer is {}., 42)需要包含fmt/format.h。格式化还支持位置参数例如fmt::format(Id rather be {1} than {0}., right, happy)输出Id rather be happy than right.。格式化用户自定义类型{fmt} 为大量标准 C 类型提供了 formatterrange/tuple 见fmt/ranges.h日期时间见fmt/chrono.h其余标准库类型见fmt/std.h。让一个自定义类型可格式化有两种方式提供format_as函数或特化formatter结构体模板。非 void 指针类型的格式化是被有意禁止的任何扩展 API 都无法让它们可格式化。方式一format_as当你想让自定义类型“以另一种类型的格式规格”被格式化时使用format_as。该函数接收你的类型对象返回一个可格式化类型的对象且必须定义在你的类型所在命名空间中#include fmt/format.h namespace kevin_namespacy { enum class film { house_of_cards, american_beauty, se7en 7 }; auto format_as(film f) { return fmt::underlying(f); } } int main() { fmt::print({}\n, kevin_namespacy::film::se7en); // 输出: 7 }注意format_as不能用于同时匹配另一个formatter特化如 range formatter的类型否则特化会产生歧义。此时应尽可能禁用冲突的特化或改为显式提供formatter特化。方式二特化formatter特化更复杂但能完全控制解析与格式化过程。推荐的做法是通过继承或组合复用现有 formatter这样无需自己实现标准格式规格。例如为枚举color定义基于formatterstring_view的 formatter// color.h: #include fmt/base.h enum class color {red, green, blue}; template struct fmt::formattercolor: formatterstring_view { // parse 从 formatterstring_view 继承。 auto format(color c, format_context ctx) const - format_context::iterator; };// color.cc: #include color.h #include fmt/format.h auto fmt::formattercolor::format(color c, format_context ctx) const - format_context::iterator { string_view name unknown; switch (c) { case color::red: name red; break; case color::green: name green; break; case color::blue: name blue; break; } return formatterstring_view::format(name, ctx); }注意formatterstring_view::format定义在fmt/format.h中因此源文件必须包含该头。由于parse继承自formatterstring_view它会识别所有字符串格式规格例如fmt::format({:10}, color::blue)将返回 blue。formatter 的一般形态如下template struct fmt::formatterT { // 解析格式规格并存储到 formatter 中。 // // [ctx.begin(), ctx.end()) 是一个可能为空的字符区间包含从待解析 // 的格式规格开始的格式字符串片段例如在 // // fmt::format({:f} continued, ...); // // 中区间内容为 f} continued。formatter 应解析到 } 或区间末尾 // 本例中应解析 f 规格并返回指向 } 的迭代器。 constexpr auto parse(format_parse_context ctx) - format_parse_context::iterator; // 用解析得到的格式规格格式化 value并写入 ctx.out()。 auto format(const T value, format_context ctx) const - format_context::iterator; };官方建议至少支持作用于整个对象的 fill、align、width且语义与标准 formatter 一致。也可以为类层次编写 formatter——利用模板特化 std::enable_if_t约束基类例如在demo.h中定义struct A与struct B : A再通过fmt::formatterT, std::enable_if_tstd::is_base_of_vA, T, char : fmt::formatterstd::string统一格式化整个继承体系fmt::print({}, a)其中A a b输出B。同时提供formatter特化与format_as重载是不允许的。编译期检查在支持 C20consteval的编译器上编译期格式字符串检查默认开启旧编译器可以使用fmt/format.h中定义的FMT_STRING宏见下文“Legacy 编译期检查”。未使用的参数是允许的这与 Python 的str.format和普通函数一致。例如fmt::format({:d}, I am not a number)在 C20 下会编译失败因为d对字符串是无效的格式规格见 README.md 的示例。类型擦除Type Erasure利用fmt::format_string与类型擦除可以编写自己的带编译期检查、且二进制体积很小的格式化函数#include fmt/format.h void vlog(const char* file, int line, fmt::string_view fmt, fmt::format_args args) { fmt::print({}: {}: {}, file, line, fmt::vformat(fmt, args)); } template typename... T void log(const char* file, int line, fmt::format_stringT... fmt, T... args) { vlog(file, line, fmt, fmt::make_format_args(args...)); } #define MY_LOG(fmt, ...) log(__FILE__, __LINE__, fmt, __VA_ARGS__) MY_LOG(invalid squishiness: {}, 42);关键点在于vlog不依赖参数类型与完全模板化的版本相比能显著缩短编译时间并减小二进制代码体积。相关核心类型包括make_format_args(T...)从参数构造类型擦除的参数包basic_format_args/format_args类型擦除后的参数集合basic_format_arg单个类型擦除的参数。命名参数通过fmt::arg(const char*, const T)可以为参数命名配合{name}引用。例如fmt::format({greeting}, {name}!, fmt::arg(greeting, hi), fmt::arg(name, fmt)); // 结果: hi, fmt!兼容性fmt::basic_string_view/fmt::string_view提供了轻量的字符串视图用于在无需std::string_view依赖的场合接收字符串参数是fmt/base.h中const char*、fmt::string_viewformatter 所覆盖的类型之一。完整格式化 APIfmt/format.hfmt/format.h定义完整的格式化 API提供额外的格式化函数与 locale 支持format(format_stringT..., T...)格式化并返回std::stringvformat(string_view, format_args)接收类型擦除参数包的格式化operator_a()在fmt::literals中定义的字面量可将name_a value形式的表达式用于命名参数构造。工具函数ptr(T)将对象指针格式化为其地址fmt::format({}, fmt::ptr(obj))underlying(Enum)取枚举的底层值format_as示例中的fmt::underlying(f)to_string(const T)等价于fmt::format({}, value)group_digits(T)对整数按千位分组例如fmt::format({}, fmt::group_digits(1234567))detail::buffer格式化输出底层缓冲抽象basic_memory_buffer动态增长的栈上/堆上混合内存缓冲是format_to系列函数的常用输出目标也是自定义分配器与自定义格式化函数的基础。系统错误{fmt} 不使用errno向用户传递错误但它可能会调用设置errno的系统函数。用户不应假设库函数会保留errno的值。相关接口system_error构造携带格式化消息的std::system_errorformat_system_error将系统错误码对应的消息格式化到缓冲区。自定义分配器{fmt} 支持自定义动态内存分配器。自定义分配器类可以作为模板参数传给fmt::basic_memory_bufferusing custom_memory_buffer fmt::basic_memory_bufferchar, fmt::inline_buffer_size, custom_allocator;也可以编写使用自定义分配器的格式化函数using custom_string std::basic_stringchar, std::char_traitschar, custom_allocator; auto vformat(custom_allocator alloc, fmt::string_view fmt, fmt::format_args args) - custom_string { auto buf custom_memory_buffer(alloc); fmt::vformat_to(std::back_inserter(buf), fmt, args); return custom_string(buf.data(), buf.size(), alloc); } template typename ...Args auto format(custom_allocator alloc, fmt::string_view fmt, const Args ... args) - custom_string { return vformat(alloc, fmt, fmt::make_format_args(args...)); }分配器仅用于输出容器。对内置类型与字符串类型格式化函数通常不做任何堆分配唯一的例外是非默认浮点格式化偶尔会回退到sprintf。Locale 支持默认情况下所有格式化都与 locale 无关这保证了跨平台输出一致。使用L格式规格可从 locale 插入对应的数字分隔符#include fmt/format.h #include locale std::locale::global(std::locale(en_US.UTF-8)); auto s fmt::format({:L}, 1000000); // s 1,000,000fmt/format.h提供以下接受std::locale参数的重载locale 类型被设计为模板参数以避免昂贵的locale头文件包含format(locale_ref, format_stringT..., T...)format_to(OutputIt, locale_ref, format_stringT..., T...)formatted_size(locale_ref, format_stringT..., T...)Legacy 编译期检查FMT_STRING为旧编译器开启编译期检查要求 C14 或更高版本在 C11 下为空操作。若要强制使用 legacy 编译期检查可定义预处理变量FMT_ENFORCE_COMPILE_STRING——设置后接受FMT_STRING的函数遇到普通字符串将编译失败。Range 与 Tuple 格式化fmt/ranges.hfmt/ranges.h为 range 与 tuple 提供格式化支持#include fmt/ranges.h fmt::print({}, std::tuplechar, int{a, 42}); // 输出: (a, 42)使用fmt::join可以用自定义分隔符连接 tuple/range 元素#include fmt/ranges.h auto t std::tupleint, char{1, a}; fmt::print({}, fmt::join(t, , )); // 输出: 1, afmt::join的三种重载形式join(Range, string_view)连接整个 rangejoin(It, Sentinel, string_view)连接迭代器区间[It, Sentinel)join(std::initializer_listT, string_view)连接初始化列表。标准容器如std::vector的格式化在 README 中也有演示fmt::print({}\n, v)对std::vectorint v {1, 2, 3}输出[1, 2, 3]。日期与时间格式化fmt/chrono.hfmt/chrono.h为以下类型提供 formatterstd::chrono::durationstd::chrono::time_pointstd::tm格式语法见《Format String Syntax》的 Chrono Format Specifications 一节。示例#include fmt/chrono.h int main() { auto now std::chrono::system_clock::now(); fmt::print(The date is {:%Y-%m-%d}.\n, now); // 输出: The date is 2020-11-07. // 2020-11-07 会被替换为当前日期 using namespace std::literals::chrono_literals; fmt::print(Default format: {} {}\n, 42s, 100ms); // 输出: Default format: 42s 100ms fmt::print(strftime-like format: {:%H:%M:%S}\n, 3h 15min 30s); // 输出: strftime-like format: 03:15:30 }此外还提供gmtime(std::time_t)工具将时间戳转换为 UTC 的std::tm。从源码 include/fmt/chrono.h 可以看到duration 默认格式化为“数值 单位后缀”time_point 默认输出YYYY-MM-DD HH:MM:SS.ffffff形式见 README.md 的输出示例。标准库类型格式化fmt/std.hfmt/std.h为以下标准库类型提供 formatterstd::atomicstd::atomic_flagstd::bitsetstd::error_codestd::exceptionstd::filesystem::pathstd::monostatestd::optionalstd::source_locationstd::thread::idstd::variant此外还提供智能指针格式化工具ptr(const std::unique_ptrT, Deleter)ptr(const std::shared_ptrT)Variantsstd::variant只有在每个备选类型都可格式化时才能格式化且要求编译器支持__cpp_lib_variant特性测试宏#include fmt/std.h fmt::print({}, std::variantchar, float(x)); // 输出: variant(x) fmt::print({}, std::variantstd::monostate, char()); // 输出: variant(monostate)位域与打包结构体格式化位域bit-field或带__attribute__((packed))的结构体字段时需要通过强制转换或一元将其转换为底层或兼容类型struct smol { int bit : 1; }; auto s smol(); fmt::print({}, s.bit);这是 C 完美转发机制的一个已知限制。枚举格式化fmt/enum.hfmt/enum.h支持对用fmt::as_identifiers注解的枚举进行格式化——这样的枚举会以匹配其枚举值的枚举器标识符identifier形式输出#include fmt/enum.h enum class [[fmt::as_identifiers]] color { red, green, blue }; fmt::print({}, color::green); // 输出: green这类枚举使用字符串格式规格格式化例如fmt::print([{:7}], color::red); // 输出: [ red]由于标识符只能以char字符串形式获得注解枚举不能用其他字符类型格式化。多条规则若多个枚举器值相同按声明顺序取第一个不匹配任何枚举器的值先以十进制底层值表示再套用字符串格式化fmt::print({}, static_castcolor(42)); // 输出: 42未注解的枚举不受影响按原有方式格式化scoped enum 仍需format_as或formatter特化见上文“格式化用户自定义类型”。该特性使用两个 C26 特性reflection反射获取枚举器标识符annotations注解通过fmt::as_identifiers选择启用因此需要支持反射的编译器GCC 下可能需要额外标志如-freflection。宏FMT_USE_REFLECTION在反射可用时为1否则为0用户也可以自行定义以禁用反射。从源码 include/fmt/enum.h 可以看到检测逻辑是用户显式定义优先其次检查__cpp_impl_reflection __cpp_lib_reflection。当以模块方式构建 {fmt} 时反射支持在模块编译时检测因此只有模块以反射启用方式构建导入者才可用此 API。编译期支持fmt/compile.hfmt/compile.h提供格式字符串编译与编译期constexpr格式化通过FMT_COMPILE宏或fmt::literals中定义的_cf用户自定义字面量启用。标记了FMT_COMPILE或_cf的格式字符串会在编译期被解析、检查并转换成高效的格式化代码。它支持内置类型、字符串类型以及formatter特化中format方法以格式上下文类型为模板参数的用户自定义类型。例如struct point { double x; double y; }; template struct fmt::formatterpoint { constexpr auto parse(format_parse_context ctx) { return ctx.begin(); } template typename FormatContext 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));需要提醒与默认 API 相比格式字符串编译可能生成更多二进制代码只建议在格式化是性能瓶颈的地方使用。同一套 API 也支持在constexpr/consteval函数中进行编译期格式化。此外还有实验性的FMT_STATIC_FORMAT可在编译期格式化为精确所需大小的字符串。编译期格式化要求内置 formatter 或用户自定义 formatter 的format方法为constexprtemplate struct fmt::formatterpoint { constexpr auto parse(format_parse_context ctx) { return ctx.begin(); } template typename FormatContext constexpr auto format(const point p, FormatContext ctx) const { return format_to(ctx.out(), ({}, {})_cf, p.x, p.y); } }; constexpr auto s FMT_STATIC_FORMAT({}, point(4, 2)); const char* cstr s.c_str(); // 指向静态字符串 (4, 2)从源码 include/fmt/compile.h 看FMT_COMPILE在支持consteval时展开为FMT_STRING_IMPL(s, fmt::compiled_string)否则回退为FMT_STRING(s)FMT_STATIC_FORMAT内部先以编译后的字符串计算formatted_size再在1终止符大小的固定缓冲上完成格式化。终端颜色与文本样式fmt/color.hfmt/color.h提供终端颜色与文本样式输出支持print(text_style, format_stringT..., T...)带样式的打印fg(detail::color_type)前景色bg(detail::color_type)背景色styled(const T, text_style)将样式应用于单个值。样式可通过|组合。README 的示例展示了完整的用法#include fmt/color.h int main() { fmt::print(fg(fmt::color::crimson) | fmt::emphasis::bold, Hello, {}!\n, world); fmt::print(fg(fmt::color::floral_white) | bg(fmt::color::slate_gray) | fmt::emphasis::underline, Olá, {}!\n, Mundo); fmt::print(fg(fmt::color::steel_blue) | fmt::emphasis::italic, 你好{}\n, 世界); }fmt::color提供了大量具名颜色如crimson、floral_white、steel_blue等fmt::emphasis提供bold、italic、underline等样式。系统 APIfmt/os.hfmt/os.h提供系统级 APIostream基于 {fmt} 内部缓冲的轻量文件输出流类见 include/fmt/os.houtput_file(cstring_view, T...)打开输出文件并返回ostream对象#include fmt/os.h int main() { auto out fmt::output_file(guide.txt); out.print(Dont {}, Panic); }windows_error构造携带格式化消息的std::system_error面向 Windows 错误码源码中对应vwindows_error/report_windows_error。这些 API 可以通过 CMake 选项FMT_OSOFF整体禁用见下文“配置选项”。std::ostream支持fmt/ostream.hfmt/ostream.h提供std::ostream支持包括格式化那些已重载插入运算符operator的用户自定义类型。要让某类型通过std::ostream可格式化只需提供继承自ostream_formatter的formatter特化#include fmt/ostream.h struct date { int year, month, day; friend std::ostream operator(std::ostream os, const date d) { return os d.year - d.month - d.day; } }; template struct fmt::formatterdate : ostream_formatter {}; std::string s fmt::format(The date is {}, date{2012, 12, 9}); // s The date is 2012-12-9此外还有streamed(const T)将任意类型以流式方式格式化调用其operatorprint(std::ostream, format_stringT..., T...)格式化并输出到任意std::ostream。动态参数列表fmt/args.h头文件fmt/args.h提供dynamic_format_arg_store一种 builder 风格的 API用于动态地构造格式参数列表典型场景运行期决定参数个数如日志系统。从源码 include/fmt/args.h 可以看到其基本用法fmt::dynamic_format_arg_storefmt::format_context store; store.push_back(42); store.push_back(abc); store.push_back(1.5f); // 之后 store 可传给 vformat 系列函数使用push_back有三种重载push_back(const T)按值存入参数生命周期由 store 管理push_back(std::reference_wrapperT)以引用方式存入避免拷贝push_back(const named_argT, char_type)存入命名参数与fmt::arg生成的命名参数兼容。安全的 printffmt/printf.hfmt/printf.h提供 printf 风格的格式化功能使用 printf 格式字符串语法并支持 POSIX 位置参数扩展。与标准对应物不同fmt版本是类型安全的——如果参数类型与格式规格不匹配会抛出异常printf(string_view, const T...)输出到 stdoutfprintf(std::FILE*, string_view, const T...)输出到指定FILE*sprintf(string_view, const T...)返回std::string。宽字符串fmt/xchar.h可选的fmt/xchar.h提供wchar_t及“异国”字符类型支持wstring_view宽字符字符串视图wformat_context宽字符格式化上下文to_wstring(const T)等价于fmt::format(L{}, value)返回std::wstring。与 C20std::format的兼容性{fmt} 实现了 C20 格式化库的绝大部分功能差异如下名称定义在fmt命名空间而非std避免与标准库实现冲突宽度计算不使用 grapheme 聚类该功能曾在独立分支实现尚未合并{fmt} 的默认浮点表示使用能提供 round-trip 保证的最小精度与 Java、Python 等语言类似std::format目前按std::to_chars的语义规定——后者倾向于生成最少字符数忽略冗余数字与指数符号有时会产生比必要更多的十进制位。配置选项{fmt} 通过 CMake 选项与预处理器宏提供配置能力可启用/禁用特性并针对二进制体积优化。例如配置 CMake 时用-DFMT_OSOFF可禁用fmt/os.h中定义的 OS 专属 API。CMake 选项FMT_OS设为OFF时禁用 OS 专属 APIfmt/os.h。默认ON见 CMakeLists.txt 中option(FMT_OS Include OS-specific APIs. ON)FMT_UNICODE设为OFF时在 Windows/MSVC 上禁用 Unicode 支持其他平台 Unicode 始终启用。默认ON。宏FMT_HEADER_ONLY定义后启用 header-only 模式是fmt::fmt-header-onlyCMake target 的替代方案。默认不定义。CMakeLists.txt 中fmt-header-onlytarget 通过FMT_HEADER_ONLY1编译定义实现。FMT_USE_EXCEPTIONS设为0时禁用异常的使用。默认1以-fno-exceptions编译时为0。源码 include/fmt/base.h 中的检测逻辑用户显式定义优先否则依次检查 GCC 的__EXCEPTIONS、Clang 的__cpp_exceptions、MSVC 的_HAS_EXCEPTIONS自动判定。FMT_USE_LOCALE设为0时禁用 locale 支持。默认1FMT_OPTIMIZE_SIZE 1时为0。源码中定义为FMT_USE_LOCALE (FMT_OPTIMIZE_SIZE 1)见 include/fmt/base.h。FMT_CUSTOM_ASSERT_FAIL设为1时允许用户提供自定义的fmt::assert_fail函数它在断言失败时被调用若异常被禁用也在运行时错误时被调用。默认0。fmt::assert_fail的声明见 include/fmt/base.h。FMT_BUILTIN_TYPES设为0时禁用除int之外的算术与字符串类型的内置处理以减小库体积代价是每次调用增加额外开销。默认1。FMT_OPTIMIZE_SIZE控制二进制体积优化0关闭默认1应用部分优化2默认禁用 locale 支持、部分 Unicode 特性与命名参数并应用更激进的优化。二进制体积优化为了在尽可能减小 {fmt} 二进制体积代价是损失部分特性时可使用如下配置CMake 选项FMT_OSOFF宏FMT_BUILTIN_TYPES0FMT_OPTIMIZE_SIZE2延伸阅读《Format String Syntax》完整的格式字符串语法包括替换字段文法、fill/align/sign/width/precision/type 等格式规格的逐项说明《Getting Started》编译与接入方式CMake、header-only、模块入门示例打印、格式化、日期时间、容器、文件输出、彩色输出的完整代码测试目录 test/ 下的base-test.cc、format-test.cc、chrono-test.cc、ranges-test.cc、std-test.cc、enum-test.cc、compile-test.cc、xchar-test.cc、printf-test.cc、args-test.cc、os-test.cc等文件可作为各 API 行为的可执行验证。【免费下载链接】fmtA modern formatting library项目地址: https://gitcode.com/GitHub_Trending/fm/fmt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
