Chapter 40: SFINAE

SFINAE 处理的是模板代码中的一个核心问题：泛型接口面对不同类型时，某些候选实现会在替换模板参数后失效，编译器如何把这些失效候选从重载集合中移除，并让剩余候选继续完成普通重载决议。读完本章后，读者应能追踪一个模板调用从候选生成、参数替换、候选过滤到最终重载选择的完整路径。

本章的贯穿材料是一个 append_value 接口。它面对两类对象：一类对象有 push_back(int) 成员，另一类对象是裸指针输出位置。我们用这个接口观察 SFINAE 如何把“这个类型有没有某个操作”转成候选函数的可用性判断，再把这个判断迁移到 std::enable_if、std::void_t、检测 idiom 和 STL 常见源码形状中。

SFINAE 的标准语义细节可以对照 cppreference 的 SFINAE 页面。本章使用这些规则形成工程化读法：先看失败是否发生在模板参数替换阶段，再看失败位置是否属于 immediate context，再看候选被过滤后是否还有可行重载，最后再判断 STL 接口为何选择这条约束写法。

#include <iostream>
#include <list>
#include <vector>

// 候选 A：只有当 T 支持 push_back(int) 时才成立。
template<class T>
auto append_value(T& xs, int value) -> decltype(xs.push_back(value), void()) {
    xs.push_back(value);
}

// 候选 B：裸指针输出位置。
void append_value(int* out, int value) {
    *out = value;
}

int main() {
    std::vector<int> v;
    std::list<int> l;
    int slot = 0;

    append_value(v, 1);     // 选择候选 A
    append_value(l, 2);     // 选择候选 A
    append_value(&slot, 3); // 候选 A 替换失败，选择候选 B

    std::cout << v.front() << ' ' << l.front() << ' ' << slot << '\n';
}

这段代码中的 decltype(xs.push_back(value), void()) 是观察点。decltype 操作数处在未求值语境中，表达式本身用于检查类型合法性。xs.push_back(value) 对 std::vector<int> 和 std::list<int> 合法，候选 A 的返回类型替换成功。xs.push_back(value) 对 int* 失效，候选 A 在形成重载集合时被移除，调用继续匹配候选 B。

40.1 SFINAE 是什么

SFINAE 的全称是 substitution failure is not an error，工作定义是：在函数模板重载决议或类模板偏特化匹配中，模板参数替换导致某个候选的函数类型、模板参数声明或偏特化参数表失效时，这个候选从匹配集合中移除；只要还有其他候选能完成匹配，整个调用仍然是良构程序。

这个定义中的“替换”指编译器把显式模板实参、推导得到的模板实参和默认模板实参放入模板声明中。替换发生在候选形成阶段，早于函数体语句检查。贯穿材料中的候选 A 能被 SFINAE 处理，原因在于失败点位于返回类型 decltype(xs.push_back(value), void())，它属于函数类型的一部分。

SFINAE 的边界集中在 immediate context。immediate context 可以理解为当前模板声明表面直接出现的类型和表达式，例如返回类型、形参类型、模板参数默认实参、偏特化参数表。替换这些位置时出现的失效可以触发候选移除。替换过程触发更深层实例化后产生的错误通常会成为硬错误，例如实例化某个辅助类模板时，它的类体内部访问了不存在的成员，这种错误已经离开了当前声明表面。

#include <type_traits>

struct WithType { using value_type = int; };
struct WithoutType {};

template<class T>
auto read_value_type(int) -> typename T::value_type;

template<class>
auto read_value_type(...) -> void;

static_assert(std::is_same_v<decltype(read_value_type<WithType>(0)), int>);
static_assert(std::is_same_v<decltype(read_value_type<WithoutType>(0)), void>);

这个例子把 SFINAE 的最小形态固定下来：typename T::value_type 对 WithoutType 替换失败，第一个候选被移除，省略号候选保留下来。这里没有调用函数体，decltype 只读取返回类型；因此这个例子验证的是候选声明是否成立。

读 STL 源码时，遇到一组模板重载先判断失效点是否写在声明表面。若约束表达在返回类型、额外模板参数或形参类型中，它多半参与候选过滤。若错误出现在函数体内部，调用点通常会得到硬错误，错误位置也会深入到模板实例化栈中。

40.2 substitution failure as overload filtering

把 SFINAE 看成 overload filtering，可以得到更稳定的编译期路径：编译器先收集同名候选，再对函数模板候选执行模板参数推导和替换，替换失败的候选被删除，剩余候选再进入普通重载决议。SFINAE 只负责过滤候选集合，最终选择规则仍由重载决议完成。

下面的图只描述函数模板调用的一条核心路径，省略了 ADL、访问控制、非模板候选排序等细节。它的作用是把“替换失败”和“重载选择”分成两个阶段。

贯穿材料中的 append_value(&slot, 3) 正好走过这条路径。编译器看到函数模板候选 A 和普通函数候选 B。候选 A 推导出 T = int*，接着把 T 放入返回类型中的 xs.push_back(value)。由于 int* 没有成员 push_back，候选 A 被移除。候选 B 的形参是 int* 和 int，调用成立。

SFINAE 过滤结束后，剩余候选之间没有特殊待遇。若两个候选都替换成功并且转换等级相同，普通重载决议会报告二义性。若所有候选都被移除，调用点也会得到错误。这个结论对调试模板错误很直接：先确认候选是否被过滤，再确认剩余候选排序是否唯一。

#include <type_traits>

template<class T>
auto twice(T x) -> decltype(x + x) {
    return x + x;
}

void twice(...) {}

struct Token {};

int main() {
    twice(1);       // 模板候选成立，返回 int
    twice(Token{}); // 模板候选过滤，省略号候选成立
}

这里的 decltype(x + x) 属于表达式 SFINAE。Token{} + Token{} 不合法，模板候选被移除。省略号候选保留，调用依然有落点。若删除省略号候选，twice(Token{}) 会在调用点得到无可用重载的诊断。

40.3 enable_if

std::enable_if 把布尔条件转成“是否存在 type 成员”的类型问题。根据 cppreference 的 std::enable_if 页面，条件为真时 std::enable_if<B, T> 提供成员类型 type，条件为假时没有该成员。这个缺失成员被放在 SFINAE 位置后，就能控制候选是否进入重载集合。

#include <iostream>
#include <type_traits>

template<class T, std::enable_if_t<std::is_integral_v<T>, int> = 0>
void print_number(T value) {
    std::cout << "integral: " << value << '\n';
}

template<class T, std::enable_if_t<std::is_floating_point_v<T>, int> = 0>
void print_number(T value) {
    std::cout << "floating: " << value << '\n';
}

int main() {
    print_number(42);
    print_number(3.14);
}

这个例子把 enable_if 放在非类型模板参数位置。print_number(42) 推导出整数类型，第一个候选的 std::enable_if_t<true, int> 成立，第二个候选的 std::enable_if_t<false, int> 替换失败。print_number(3.14) 的方向相反。两个重载的函数形参表面相同，约束通过额外模板参数参与候选过滤。

enable_if 常见放置位置有三个：返回类型、额外函数参数、额外模板参数。返回类型写法适合普通函数模板，但构造函数没有返回类型，析构函数也没有返回类型，因此容器构造函数一类场景常把 enable_if 放到模板参数中。额外函数参数会改变调用表面，通常用于内部实现函数或带默认实参的辅助重载。

#include <type_traits>

struct SizeTag {};
struct IteratorTag {};

template<class T, std::enable_if_t<std::is_integral_v<T>, int> = 0>
SizeTag classify(T) {
    return {};
}

template<class It, std::enable_if_t<!std::is_integral_v<It>, int> = 0>
IteratorTag classify(It) {
    return {};
}

static_assert(std::is_same_v<decltype(classify(3)), SizeTag>);
static_assert(std::is_same_v<decltype(classify(static_cast<int*>(nullptr))), IteratorTag>);

这个形状接近早期序列容器构造函数常见的判断：两个实参都像整数时走“数量 + 初值”的构造路径，实参像迭代器时走区间构造路径。真实标准库实现还会结合 iterator traits、concepts 或内部约束工具，但源码读法一致：先定位约束条件，再判断它控制的是候选存在性、偏特化匹配，还是函数体内部路径。

40.4 void_t

std::void_t 把任意一组类型映射成 void。根据 cppreference 的 std::void_t 页面，它从 C++17 起定义在 <type_traits> 中，常用于在未求值语境里检查表达式是否合法，并把检查结果接入 SFINAE。

void_t 的价值在于压缩检测写法。检测时的核心问题是表达式能否形成，表达式的实际类型通常只是进入替换过程的过渡材料。只要表达式能形成，void_t<表达式类型> 就得到 void，偏特化匹配成功；只要表达式失效，偏特化被过滤，主模板保留。

#include <type_traits>
#include <utility>
#include <vector>

struct NoAppend {};

template<class, class = void>
struct has_push_back_int : std::false_type {};

template<class T>
struct has_push_back_int<
    T,
    std::void_t<decltype(std::declval<T&>().push_back(std::declval<int>()))>
> : std::true_type {};

static_assert(has_push_back_int<std::vector<int>>::value);
static_assert(!has_push_back_int<NoAppend>::value);

这段代码中，主模板表达默认结论：类型不支持 push_back(int)。偏特化表达检查路径：把 T& 放入 push_back 调用表达式，并取 decltype。对 std::vector<int>，表达式成立，void_t 得到 void，偏特化匹配。对 NoAppend，表达式失效，偏特化被移除，主模板生效。

std::declval<T&>() 在这里只生成类型层面的表达式，服务于 decltype 检查。它不会构造对象，也不会执行 push_back。这点决定了 void_t 检测只回答“表达式形式是否合法”，不会回答运行期容量、异常安全、迭代器失效或容器当前状态。

C++17 之前也能手写 void_t，常见实现是 make_void 辅助类。工程代码里看到这种写法时，应结合目标标准版本判断原因：库可能需要兼容 C++11 或 C++14，也可能为了绕过早期编译器对 alias template 替换的旧缺陷。

40.5 检测 idiom

检测 idiom 把 void_t 的一次性检测整理成可复用的能力查询工具。它的输入是一段表达式模板，例如“对 T& 调用 push_back(int)”，输出是一个布尔型 traits。这个 traits 可以进入 enable_if、static_assert、分支选择或内部适配层。

#include <type_traits>
#include <utility>
#include <vector>

template<class T>
using push_back_int_expr = decltype(
    std::declval<T&>().push_back(std::declval<int>())
);

template<template<class> class Expr, class T, class = void>
struct is_detected : std::false_type {};

template<template<class> class Expr, class T>
struct is_detected<Expr, T, std::void_t<Expr<T>>> : std::true_type {};

template<class T>
constexpr bool has_push_back_int_v = is_detected<push_back_int_expr, T>::value;

struct Sink {};

static_assert(has_push_back_int_v<std::vector<int>>);
static_assert(!has_push_back_int_v<Sink>);

这段代码把检测拆成两层。push_back_int_expr<T> 只描述要检查的表达式。is_detected 只负责把表达式是否成立转成 true_type 或 false_type。这比在每个重载上重复写 std::void_t<decltype(...)> 更利于维护，也更接近许多标准库内部 traits 的组织方式。

检测 idiom 的工程边界有三条。第一，它检测的是语法可形成性和类型可替换性，无法证明语义正确，例如 push_back(int) 成立并不代表插入后顺序满足业务约束。第二，它通常运行在未求值语境中，无法观察运行期状态。第三，它可能触发辅助模板实例化，若错误出现在 immediate context 之外，诊断会变成硬错误。

在 STL 读解中，检测 idiom 经常出现在“接口适配层”。例如判断某个 iterator 是否带有 iterator_category，判断 allocator 是否提供某个成员，判断一个比较器能否被调用。源码中的 traits 名称可能与标准接口不同，但判断顺序相同：先找检测表达式，再看默认结论，再看偏特化如何覆盖默认结论。

40.6 重载选择

SFINAE 完成候选过滤后，重载选择仍按照普通规则进行。这个阶段会比较参数转换等级、模板与非模板候选、偏序关系、可访问性和二义性。工程上常见误判是把“候选成立”当成“候选必然获胜”。正确读法应分成两步：候选是否通过 SFINAE，候选通过后在重载决议中的排序是否领先。

#include <iostream>
#include <type_traits>
#include <utility>
#include <vector>

struct priority_low {};
struct priority_high : priority_low {};

template<class T>
auto append_impl(T& xs, int value, priority_high)
    -> decltype(xs.push_back(value), void()) {
    xs.push_back(value);
    std::cout << "push_back\n";
}

template<class T>
auto append_impl(T& xs, int value, priority_low)
    -> decltype(xs.insert(xs.end(), value), void()) {
    xs.insert(xs.end(), value);
    std::cout << "insert\n";
}

template<class T>
void append_ordered(T& xs, int value) {
    append_impl(xs, value, priority_high{});
}

int main() {
    std::vector<int> v;
    append_ordered(v, 7);
}

std::vector<int> 同时支持 push_back 和 insert(end(), value)，两个 append_impl 模板都能替换成功。第三个实参使用 priority_high{}，高优先级重载的形参精确匹配，低优先级重载需要从派生类转换到基类，所以普通重载决议选择 push_back 路径。若类型没有 push_back 但支持 insert(end(), value)，高优先级候选先被移除，低优先级候选保留并被调用。

这个 priority tag 形状在源码中常用于表达“优先尝试更直接的接口，失败后退到通用接口”。它依赖两层机制：SFINAE 过滤掉不支持的接口，重载决议在多个可行接口中选择更高优先级。若省掉 priority tag，两个可行候选可能因转换等级相同而二义。

重载选择阶段还要区分候选过滤和约束收窄。enable_if 条件互斥时，过滤结果通常只有一个模板候选。条件有重叠时，两个候选可能同时成立；此时需要更强的偏序关系、priority tag、tag dispatch 或 concepts 约束排序来稳定选择结果。

40.7 STL 中的 SFINAE

STL 中的 SFINAE 主要服务三个目标：把接口条件放进模板声明，把类型能力查询封装成 traits，把同名接口的不同语义路径分开。它支撑的是标准库泛型接口在大量类型上保持可用诊断和可控重载集的方式，范围覆盖容器、迭代器、allocator 和算法适配层。

序列容器构造函数是典型场景。vector(n, value) 表示创建 n 个元素，vector(first, last) 表示从迭代器区间构造。两个调用在语法上都可能是两个实参，源码需要区分整数数量和迭代器范围。常见实现会使用 is_integral、iterator traits、内部 category 判断或 C++20 concepts，把不符合当前语义的候选过滤掉，防止整数被当作迭代器路径处理。

算法入口也会使用类似思想。传统算法往往通过 iterator category、traits 和重载分发选择实现路径；支持随机访问迭代器时可用距离运算，只有前向迭代器时走线性推进。SFINAE 或内部 traits 可以参与“这个实现候选是否对当前 iterator 成立”的判断，但复杂度承诺仍来自算法本身和 iterator 能力，不由 SFINAE 单独保证。

allocator 相关源码也能看到能力检测。标准库需要兼容用户自定义 allocator，某些成员函数可能存在，某些成员函数可能通过 allocator_traits 补齐。常见实现会把“是否有成员”“成员类型是否存在”“调用表达式是否成立”转成 traits，再在统一入口中选择默认行为或用户提供行为。这里的 SFINAE 主要保护接口适配层，使容器源码能用同一套路径管理分配、构造和销毁。

从 C++20 开始，concepts 把很多隐式 SFINAE 约束改成显式 constraints。旧代码和标准库兼容层仍然大量保留 SFINAE 形状，尤其在 C++11、C++14、C++17 目标库中。读源码时应把 concepts 和 SFINAE 放在不同层级：concepts 提供更清晰的约束声明和诊断，SFINAE 提供替换失败驱动的候选过滤，二者都服务泛型接口约束。

本章的 STL 判断顺序可以固定为五步：先定位约束写在返回类型、形参、模板参数还是偏特化参数表；再判断失败点是否属于 immediate context；接着判断过滤后剩余候选数量；然后检查普通重载决议的排序依据；最后把选择结果放回容器、算法或 traits 的语义目标中，确认它解决的是数量构造、区间构造、能力检测还是实现路径选择。

最小自检任务

阅读下面代码，判断三个 call 表达式分别选择哪个重载，并说明哪一步属于 SFINAE 过滤，哪一步属于普通重载决议。

#include <type_traits>
#include <utility>
#include <vector>

struct Low {};
struct High : Low {};

struct WithReserve {
    void reserve(int) {}
};

struct WithSizeOnly {
    int size() const { return 0; }
};

template<class T>
auto call_impl(T& obj, High) -> decltype(obj.reserve(1), int{}) {
    return 1;
}

template<class T>
auto call_impl(T& obj, Low) -> decltype(obj.size(), long{}) {
    return 2L;
}

int call_impl(...) {
    return 3;
}

template<class T>
auto call(T& obj) {
    return call_impl(obj, High{});
}

int main() {
    WithReserve a;
    WithSizeOnly b;
    int c = 0;

    auto x = call(a);
    auto y = call(b);
    auto z = call(c);
}

答案要点

call(a) 选择第一个 call_impl，返回 int。WithReserve 支持 reserve(1)，高优先级候选替换成功；低优先级候选要检查 size()，对 WithReserve 失效并被过滤；省略号候选虽然可行，但普通重载决议会优先选择具体模板候选。

call(b) 选择第二个 call_impl，返回 long。高优先级候选中的 obj.reserve(1) 替换失败，被 SFINAE 移除；低优先级候选中的 obj.size() 替换成功。调用实参是 High{}，它可以转换成 Low，所以第二个候选可行并胜过省略号候选。

call(c) 选择省略号候选，返回 int。int 同时缺少 reserve 和 size 成员，两个函数模板候选都在返回类型替换阶段被移除。剩余候选只有 call_impl(...)，普通重载决议没有二义性。

本章知识点总结

SFINAE 定义：模板参数替换在声明表面失效时，相关候选会从匹配集合中移除，剩余候选继续完成决议。
替换阶段：显式实参、推导实参和默认实参会被放入函数类型、模板参数声明或偏特化参数表中检查。
声明表面：返回类型、形参类型和模板参数默认实参等 immediate context 位置可以承载 SFINAE 过滤。
硬错误边界：替换触发更深层实例化后产生的错误通常会成为硬错误，诊断会进入模板实例化栈。
候选过滤：SFINAE 只删除失效候选，最终调用仍由普通重载决议选择唯一最佳候选。
enable_if：std::enable_if 把布尔条件转成成员类型是否存在的问题，常放在返回类型、形参或模板参数中。
构造函数约束：构造函数没有返回类型，容器源码常把 enable_if 放在模板参数位置表达候选过滤。
void_t：std::void_t 把表达式合法性检查压缩成 void 替换问题，适合实现成员和表达式检测。
检测 idiom：检测 idiom 把一次性 void_t 检查封装成可复用 traits，便于接口适配层统一查询类型能力。
优先级重载：priority tag 结合 SFINAE 可以先尝试专用接口，再回退到通用接口，并保持普通重载决议可控。
STL 场景：容器构造、iterator traits、allocator traits 和算法实现路径都可能使用 SFINAE 或等价约束技术。
判断顺序：读 SFINAE 源码时先看约束位置，再看 immediate context，再看候选集合，最后看重载排序和接口语义目标。

40.1 SFINAE 是什么​

40.2 substitution failure as overload filtering​

40.3 enable_if​

40.4 void_t​

40.5 检测 idiom​

40.6 重载选择​

40.7 STL 中的 SFINAE​

最小自检任务​

答案要点​

本章知识点总结​