C++里藏得最深的“格式化开关”：num_put 实战手记

写C++输出数字，你大概率用过 std::cout << 12345.678 << std::endl;，也调过 std::setprecision(2) 或 std::hex。但有没有哪次——比如导出财务报表时小数点后必须强制补零、或处理多语言环境下的千位分隔符（德语用点、法语用空格、中文不用）——发现 std::locale 和 std::ios_base::imbue() 突然不灵了？这时候，std::num_put 就不是“可选项”，而是你代码里唯一能真正接管数字落地形态的底层阀门。

它不常露面，但一旦需要稳定、可复现、跨平台一致的数字文本化行为，它就是那个你绕不开的“最后一公里”。

num_put 是标准库中 std::locale 的 facet 之一，专责把数值类型（int、double、long long 等）按当前 locale 规则“翻译”成字符序列。它不负责流控制，也不管缓冲区，只干一件事：给定一个数字和一个输出迭代器，吐出符合规则的字符流。这种“无状态、纯函数式”的设计，让它天然适合嵌入日志系统、序列化模块或需要规避 std::cout 全局状态污染的场景。

举个实在例子：你想把 1234567.89 格式化为德语习惯的 "1.234.567,89"，且不依赖全局 std::cout 的 imbue 设置（比如多线程下不敢动全局流）。你可以这样写：

#include <locale>
#include <sstream>
#include <string>

std::string to_german_double(double value) {
    std::ostringstream oss;
    // 显式绑定德语 locale，不影响其他流
    oss.imbue(std::locale("de_DE.UTF-8"));
    oss << std::fixed << std::setprecision(2) << value;
    return oss.str();
}

这看似干净，但有个隐患：std::ostringstream 内部仍会走 num_put，而它的行为受 locale 中 num_put facet 控制——但你无法直接定制这个 facet 的逻辑。比如，你希望千位分隔符是 ''（英文单引号）而非 '.'，或者要求整数部分不足4位时不加任何分隔符（即 999 → "999"，但 1000 → "1'000"），标准 num_put 做不到——它只认 locale 数据库里的规则，不接受运行时策略注入。

这时候，就得亲手“换芯”：继承 std::num_put<char>，重写 do_put。注意，不是“覆盖”，而是精准干预特定环节。比如，标准 do_put 在插入千位分隔符前，会查 std::use_facet<std::numpunct<char>>(loc).thousands_sep()。你完全可以在这个环节加一层判断：

struct custom_num_put : std::num_put<char> {
protected:
    iter_type do_put(iter_type out, std::ios_base& ios,
                     char_type fill, long double v) const override {
        // 先让基类生成基础字符串（不含分隔符）
        std::string base = std::to_string(static_cast<long long>(v));
        // 手动插入分隔符：每3位加一个单引号，但仅当长度≥4
        if (base.size() >= 4) {
            std::string result;
            size_t pos = base.size();
            while (pos > 0) {
                result = base.substr(pos-1, 1) + result;
                pos--;
                if (pos > 0 && pos % 3 == 0) result = "'" + result;
            }
            for (char c : result) *out++ = c;
            return out;
        }
        // 否则原样输出
        for (char c : base) *out++ = c;
        return out;
    }
};

关键来了：如何让流用你的 custom_num_put？ 不是改 std::cout，而是构造一个带自定义 facet 的 locale：

std::locale german_with_quote(std::locale("de_DE.UTF-8"),
    new custom_num_put); // 注意内存管理：new 出来，locale 会 delete
std::ostringstream oss;
oss.imbue(german_with_quote);
oss << 1234567LL; // 输出 "1'234'567"

这里有个易踩坑点：std::locale 构造时传入的 facet 指针，由 locale 自动管理生命周期。别用栈对象或智能指针传进去——它会直接 delete。这是很多初学者调试半天发现程序崩在析构期的原因。

再进一步：如果你的项目要支持“动态切换格式策略”（比如用户设置界面选“紧凑模式”/“财务模式”），可以把 custom_num_put 设计成模板类，接收一个策略结构体：

struct CompactPolicy { static constexpr char sep = '\0'; };
struct FinancePolicy { static constexpr char sep = '\''; };

template<typename Policy>
struct policy_num_put : std::num_put<char> { /* ... */ };

这样，编译期就决定行为，零运行时开销，还彻底避开虚函数调用成本。

最后说句实在话：num_put 不是日常开发的“首选工具”。90% 的场景，std::format（C++20）或 fmt::format 更直观安全。但当你在嵌入式环境受限于标准库版本、或在高频日志模块里追求确定性性能、又或需要对接银行级精度要求（比如 long double 的精确舍入控制）时，num_put 提供的是不可替代的底层掌控力——它不炫技，但稳如锚点。

下次看到数字输出不符合预期，别急着翻 stackoverflow 搜 setfill，先问问自己：这个格式，是流的状态问题，还是 num_put 的规则问题？答案往往就在那几行被忽略的 facet 重写里。