std::format要求自定义类型必须显式特化formatter模板，否则编译失败；错误提示为“no matching function for call to 'format'”或“formatter is not a valid formatter”。
std::format 要求类型必须支持 formatter 特化
直接对自定义类型调用 std::format 会编译失败，错误信息类似：no matching function for call to 'format' 或更具体的 formatter<t> is not a valid formatter</t>。这是因为 std::format 不像 operator 那样自动回退——它严格依赖 <code>std::formatter 的显式特化。
你必须为类型 T 手动提供一个特化，且该特化需满足两个条件：
- 继承自
std::formatter<char>（或std::formatter<wchar_t>） - 实现
parse()和format()成员函数
最简可行的 formatter 特化写法
假设有一个结构体 Point：
struct Point {
int x, y;
};
为其添加基础格式化支持（仅支持空格式说明符，如 {}）：
立即学习“C++免费学习笔记（深入）”；
template<>
struct std::formatter<Point> : std::formatter<std::string> {
auto format(const Point& p, format_context& ctx) const -> format_context::iterator {
return std::format_to(ctx.out(), "({},{})", p.x, p.y);
}
};
注意三点：
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
- 这里继承
std::formatter<std::string>是为了复用其parse()（默认接受空字符串），避免自己写空parse函数 -
format()必须返回format_context::iterator，推荐用std::format_to直接写入ctx.out() - 不能在
format()里调用std::format自身（会递归实例化），必须用std::format_to
支持自定义格式说明符（比如 "x"、"y"、"hex"）
若想支持 {:.x} 或 {:hex} 这类占位符，就必须自己实现 parse()，并用成员变量缓存解析结果：
template<>
struct std::formatter<Point> {
char presentation = 'd'; // 默认行为
constexpr auto parse(format_parse_context& ctx) -> format_parse_context::iterator {
auto it = ctx.begin();
if (it != ctx.end() && *it == 'x') { presentation = 'x'; ++it; }
else if (it != ctx.end() && *it == 'y') { presentation = 'y'; ++it; }
else if (it != ctx.end() && *it == 'h') { presentation = 'h'; ++it; }
return it;
}
template <typename FormatContext>
auto format(const Point& p, FormatContext& ctx) const -> FormatContext::iterator {
if (presentation == 'x') return std::format_to(ctx.out(), "{}", p.x);
if (presentation == 'y') return std::format_to(ctx.out(), "{}", p.y);
if (presentation == 'h') return std::format_to(ctx.out(), "(0x{:x},0x{:x})", p.x, p.y);
return std::format_to(ctx.out(), "({},{})", p.x, p.y);
}
};
关键细节：
-
parse()接收format_parse_context&，不是format_context - 解析失败时应抛出
std::format_error（例如遇到未知字符），否则行为未定义 -
presentation字段必须是constexpr友好类型（char、int、string_view等），不能是std::string
格式化器必须在使用前声明，且不可在匿名命名空间中定义
常见错误是把 std::formatter<Point> 特化写在 .cpp 文件里，或包在 namespace { } 中——这会导致链接时其他 TU（translation unit）看不到特化，依然报错“no formatter found”。
正确做法：
- 将特化放在头文件中（与
Point定义同头文件，或单独point_format.h） - 确保包含该头文件的每个源文件都能看到特化定义（即不能只在某个
.cpp里定义） - 如果
Point是模板类，formatter特化也必须是模板，并用template<class T> struct std::formatter<MyVec<T>>形式
另外，C++20 标准库不支持 ADL 查找用户定义的 formatter，所有特化都必须针对 std::formatter 命名空间全限定名，不能靠 using 或别名绕过。
