Skip to content
Tutorials Center
My learning

Topics

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.

C++
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

C++ enable_if selects an overload

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.

C++ Detecting a member, and the C++20 version

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

C++
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_if overloads must not both be viable, and two templates that differ only in a default template argument are the same declaration (a redefinition). Using std::enable_if_t<cond, int> = 0 as a non-type parameter avoids this.
  • Overload ranking tricks. The int/long argument 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 constexpr when 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_t is the standard way to write detection traits for members, nested types and expressions; C++20 requires expressions 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-depth or move to concepts when diagnostics get unreadable.
  • Library idiom: std::enable_if is how pre-C++20 standard library implementations constrain constructors (for example std::pair).
  • std::is_detected from the library fundamentals TS is not in C++23; write your own with void_t.