C++ Reference ยท Types and Language Concepts
SFINAE: substitution failure is not an error
Reference for C++ SFINAE: how failed template argument substitution removes an overload, std::enable_if, detection idioms and the modern alternatives.
SFINAE stands for "substitution failure is not an error". When the compiler tries a function template for a call, it replaces the template parameters with the deduced types. If that produces an invalid type or expression in the function's immediate signature, the template is silently dropped from the candidate set instead of causing a compile error. Only if no candidate is left do you get an error.
This rule is the old way to enable or disable overloads depending on properties of the types: "this overload exists only for integers", "this one only if T has a size() member". Since C++17 if constexpr and since C++20 concepts cover most of those uses with far clearer code, but SFINAE still appears in a lot of existing libraries.
template <typename T> std::enable_if_t<std::is_integral_v<T>, T> half(T x) { return x / 2; } // half(8) works; half(2.5) finds no viable overload
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
template <typename T, std::enable_if_t<condition<T>, int> = 0> // non-type parameter, recommended R f(T); template <typename T> std::enable_if_t<condition<T>, R> f(T); // in the return type template <typename T> auto f(T t) -> decltype(expression_using(t)); // expression SFINAE
| Tool | Purpose |
|---|---|
std::enable_if_t<B, T> |
Is T when B is true, otherwise no type member and the substitution fails. |
std::void_t<...> |
Becomes void if all types are valid; used in partial specializations to detect things. |
std::declval<T>() |
Produces an expression of type T&& in unevaluated contexts, without needing a constructor. |
decltype(expr) |
Fails substitution if expr is invalid. |
Traits (std::is_integral_v etc.) |
Conditions from <type_traits>. |
Usage notes
- Only the immediate context counts. An error inside the body of the function, or inside another template that the signature instantiates, is a hard error, not a substitution failure.
- Ambiguity. Two
enable_ifoverloads must not both be viable, and two templates that differ only in a default template argument are the same declaration (a redefinition). Usingstd::enable_if_t<cond, int> = 0as a non-type parameter avoids this. - Overload ranking tricks. The
int/longargument above prefers the better match and falls back to the other overload. Tag dispatch (std::true_type{}/std::false_type{}arguments) is a related technique. - Replace with
if constexprwhen you only need different code paths inside one function body; the discarded branch is not instantiated. - Replace with concepts when you need to restrict which types are accepted: the error message names the failed requirement instead of showing screens of substitution notes.
- Partial specialization with
void_tis the standard way to write detection traits for members, nested types and expressions; C++20requiresexpressions do the same inline. - Hard to read and debug. Failed overload sets show up as "no matching function" with a list of rejected candidates. Compile with
-fconcepts-diagnostics-depthor move to concepts when diagnostics get unreadable. - Library idiom:
std::enable_ifis how pre-C++20 standard library implementations constrain constructors (for examplestd::pair). std::is_detectedfrom the library fundamentals TS is not in C++23; write your own withvoid_t.