SFINAE

Overview

Template overload resolution generates candidate functions for every matching template. When the compiler substitutes concrete types into those templates, some substitutions may produce invalid expressions — a missing member, an incompatible conversion, an inapplicable operator. SFINAE says: that invalidity is not a hard error; the candidate is silently discarded.

The rule applies only during substitution — while the compiler constructs the function signature, return type, template parameter list, and default arguments. Errors inside the function body are still hard errors. This distinction is load-bearing: it means you can test whether a type supports an operation without actually calling it.

SFINAE predates C++11, but the tooling around it — std::enable_if, std::void_t, std::declval — arrived with or after C++11, making SFINAE practical for everyday constraints rather than heroic TMP gymnastics. Since C++17, if constexpr covers a large class of use cases more cleanly; since C++20, concepts replace SFINAE for overload and class constraints. Knowing SFINAE remains essential for reading existing library and framework code and for targeting pre-C++17 environments.

Syntax

The substitution rule in raw form

// Two overloads; the compiler selects whichever substitution succeeds.
template <typename T>
auto serialize(const T& v) -> decltype(v.to_string())  // trailing return type: C++11
{
    return v.to_string();
}

template <typename T>
auto serialize(const T& v) -> decltype(std::to_string(v))
{
    return std::to_string(v);
}

If T has a .to_string() member, the first overload is viable. If not, the decltype expression is ill-formed during substitution, the overload is silently dropped, and resolution falls through to the second.

std::enable_if (C++11)

std::enable_if<B, T> exposes a member type type equal to T only when B is true. When B is false, the specialisation has no type, and any expression referencing it triggers substitution failure.

#include <type_traits>

// Return-type SFINAE — C++11
template <typename T>
std::enable_if_t<std::is_integral_v<T>, T>   // enable_if_t alias: C++14; _v helper: C++17
clamp_to_byte(T v)
{
    if (v < 0)   return T{0};
    if (v > 255) return T{255};
    return v;
}

// Non-type dummy parameter form — harder to bypass than the default-type-arg form
template <typename T, std::enable_if_t<std::is_floating_point_v<T>, int> = 0>
T clamp_to_byte(T v)
{
    return static_cast<T>(clamp_to_byte(static_cast<long long>(v)));
}

enable_if_t is a C++14 alias for typename enable_if<B>::type. In C++11, write the full form.

std::void_t (C++17)

std::void_t<...> maps any sequence of well-formed types to void. It is the canonical tool for detecting whether an expression or nested type is valid.

#include <type_traits>

// Primary: no value_type assumed
template <typename T, typename = void>
struct has_value_type : std::false_type {};

// Partial specialisation: selected only when T::value_type names a type — C++17
template <typename T>
struct has_value_type<T, std::void_t<typename T::value_type>>
    : std::true_type {};

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

Before C++17, void_t was written as a local alias; the standard blessed the pattern and gave it a home in <type_traits>.

Examples

Constraining a class template

#include <type_traits>

class Entity {};

// Repository accepts only types publicly derived from Entity — C++11/14
template <
    typename T,
    typename = std::enable_if_t<std::is_base_of_v<Entity, T>>   // _v: C++17
>
class Repository {
public:
    T    get_by_id(int id);
    void insert(const T&);
    void remove(int id);
};

struct User  : Entity {};
struct RawInt {};            // not an Entity

Repository<User>   ok;      // compiles
// Repository<RawInt> bad;  // substitution failure → clear error at declaration site

Iterator-category dispatch

#include <iterator>
#include <type_traits>

// Fast path for random-access iterators — C++11
template <typename It,
          std::enable_if_t<
              std::is_same_v<                                       // _v: C++17
                  typename std::iterator_traits<It>::iterator_category,
                  std::random_access_iterator_tag>,
              int> = 0>
void advance_n(It& it, std::ptrdiff_t n) { it += n; }

// Linear fallback for everything else — C++11
template <typename It,
          std::enable_if_t<
              !std::is_same_v<
                  typename std::iterator_traits<It>::iterator_category,
                  std::random_access_iterator_tag>,
              int> = 0>
void advance_n(It& it, std::ptrdiff_t n) { while (n-- > 0) ++it; }

The two guards are strict complements, so no ambiguity arises and exactly one overload is viable for any It.

Detection with declval and decltype

std::declval<T>() (C++11) conjures an rvalue of type T without constructing it, safe to use inside decltype expressions even for non-default-constructible types.

#include <ostream>
#include <type_traits>
#include <utility>

template <typename T, typename = void>
struct is_ostreamable : std::false_type {};

template <typename T>
struct is_ostreamable<T,
    std::void_t<                                                   // C++17
        decltype(std::declval<std::ostream&>() << std::declval<const T&>())
    >> : std::true_type {};

template <typename T>
void log(const T& v) {
    if constexpr (is_ostreamable<T>::value) {   // if constexpr: C++17
        std::cerr << v << '\n';
    } else {
        std::cerr << "<non-printable>\n";
    }
}

Best Practices

Prefer if constexpr for intra-function branching (C++17). SFINAE splits one logical function into multiple overloads, scattering related code and producing cryptic diagnostics. if constexpr keeps the logic in one place and generates far clearer errors.

// Prefer (C++17)
template <typename T>
auto safe_divide(T a, T b) {
    if constexpr (std::is_floating_point_v<T>) {
        return b == T{0} ? std::numeric_limits<T>::quiet_NaN() : a / b;
    } else {
        if (b == 0) throw std::domain_error{"integer divide by zero"};
        return a / b;
    }
}

Prefer concepts for overload and class constraints (C++20). Concepts are syntactically concise, produce human-readable error messages, and subsume overload sets automatically without mutually exclusive guards.

// C++20 — replaces the enable_if class template example above
template <typename T>
    requires std::derived_from<T, Entity>
class Repository { /* … */ };

Use the non-type dummy parameter form (enable_if_t<…, int> = 0) rather than the default-type-argument form (typename = enable_if_t<…>). A caller can explicitly supply the defaulted type argument and bypass the guard; they cannot easily override a non-type parameter default.

Keep SFINAE in the immediate context. Only expressions formed directly in the function signature participate in substitution failure. Failures inside helper templates that are then used in the signature may or may not be SFINAE-friendly depending on where the error occurs.

Common Pitfalls

Hard errors vs. substitution failures. Access-control violations on private members, missing headers, and malformed dependent names are hard errors, not substitution failures — even inside a decltype. Only expressions that produce an invalid type or expression in the immediate substitution context trigger SFINAE.

struct Foo { private: using secret = int; };

template <typename T>
void bad(T) -> typename T::secret;  // hard error on Foo: access violation, not SFINAE

Ambiguous overloads. If two enable_if guards can both evaluate to true for the same T, the compiler emits an ambiguity error that can be very difficult to diagnose. Always make conditions strictly mutually exclusive, or route dispatch through a tag type.

Two-phase lookup interaction. With dependent names inside template bodies, the compiler defers name lookup to instantiation time — after substitution is complete. Failures there are not SFINAE; they are hard errors.

enable_if does not constrain concepts-style. Unlike concepts, enable_if overloads do not subsume one another. If you add a more specific overload expecting it to "win" over a general one, you may get ambiguity instead.

std::void_t and Partial Specialisation (C++17)

std::void_t maps any number of well-formed type arguments to void. That sounds trivial, but it is the exact lever needed to drive partial specialisation for detection purposes.

Why void_t works

Partial specialisation is chosen over the primary template when the compiler can form a valid substitution for all template arguments. The trick is to embed the expression you want to test inside void_t<…>: if the expression is ill-formed, void_t itself has a substitution failure and the specialisation is dropped; if it is well-formed, void_t<expr> is void, which matches the defaulted void argument on the primary template and the specialisation wins.

// Primary: assumes T has no .foo() member
template <typename T, typename = void>
struct has_foo : std::false_type {};

// Specialisation: selected only when decltype(declval<T>().foo()) is well-formed
template <typename T>
struct has_foo<T, std::void_t<decltype(std::declval<T>().foo())>>
    : std::true_type {};

The second template argument is void in both the primary (defaulted) and the specialisation (via void_t). Without void_t, you would need the second argument to literally be the decltype expression — but then primary and specialisation would have different second arguments and the specialisation would never match the default. void_t collapses any valid type to void, unifying the two.

Detecting member types and functions

#include <type_traits>
#include <utility>

// Detect nested type alias
template <typename T, typename = void>
struct has_iterator : std::false_type {};

template <typename T>
struct has_iterator<T, std::void_t<typename T::iterator>>
    : std::true_type {};

// Detect callable with a specific signature
template <typename T, typename = void>
struct has_serialize : std::false_type {};

template <typename T>
struct has_serialize<T,
    std::void_t<decltype(std::declval<T>().serialize(std::declval<std::ostream&>()))>>
    : std::true_type {};

// Detect operator== between two types
template <typename T, typename U = T, typename = void>
struct is_equality_comparable : std::false_type {};

template <typename T, typename U>
struct is_equality_comparable<T, U,
    std::void_t<decltype(std::declval<const T&>() == std::declval<const U&>())>>
    : std::true_type {};

std::void_t is available in <type_traits> since C++17. For C++14 and earlier, define it locally:

// Pre-C++17 polyfill
template <typename...>
using void_t = void;

The Detection Idiom (Walter Brown, N4502)

Walter Brown's 2015 paper N4502 "Proposing Standard Library Support for the C++ Detection Idiom" generalised the void_t pattern into a reusable vocabulary. The detection idiom did not make it into C++17 as a library feature, but the pattern is widely replicated in production codebases and remains the canonical pre-Concepts way to test whether an arbitrary expression is valid.

The nonesuch sentinel

The idiom needs a type that is deliberately unmatchable — a sentinel that signals "no type was found". The nonesuch struct serves this role:

struct nonesuch {
    nonesuch()                         = delete;
    ~nonesuch()                        = delete;
    nonesuch(const nonesuch&)          = delete;
    void operator=(const nonesuch&)    = delete;
};

nonesuch cannot be constructed, destroyed, or copied. No real C++ expression can produce a value of this type, making it a clean sentinel distinguishing "detection succeeded" from "detection failed".

The detector implementation

#include <type_traits>

// Internal helper — not part of the public interface
template <
    typename Default,
    typename AlwaysVoid,
    template <typename...> class Op,
    typename... Args>
struct detector {
    using value_t = std::false_type;
    using type    = Default;
};

template <
    typename Default,
    template <typename...> class Op,
    typename... Args>
struct detector<Default, std::void_t<Op<Args...>>, Op, Args...> {
    using value_t = std::true_type;
    using type    = Op<Args...>;
};

// Public interface
template <template <typename...> class Op, typename... Args>
using is_detected = typename detector<nonesuch, void, Op, Args...>::value_t;

template <template <typename...> class Op, typename... Args>
using detected_t = typename detector<nonesuch, void, Op, Args...>::type;

template <typename Default, template <typename...> class Op, typename... Args>
using detected_or_t = typename detector<Default, void, Op, Args...>::type;

Using the detection idiom

Define an alias template for the expression you want to probe, then pass it to is_detected:

// Expression aliases — each names the result type of the operation
template <typename T>
using serialize_expr = decltype(std::declval<T>().serialize(std::declval<std::ostream&>()));

template <typename T>
using size_expr = decltype(std::declval<const T&>().size());

template <typename T>
using value_type_expr = typename T::value_type;

// Detection queries
static_assert(is_detected<serialize_expr, MyType>::value, "MyType must have serialize()");

// detected_t yields the actual return type, or nonesuch on failure
using SizeType = detected_t<size_expr, std::vector<int>>;  // std::size_t

// detected_or_t provides a fallback type
using ValueT = detected_or_t<int, value_type_expr, MyContainer>;  // MyContainer::value_type or int

is_detected makes detection composable: you can combine multiple checks with std::conjunction and std::disjunction without nesting void_t calls.

Expression SFINAE with decltype and Trailing Return Types

Before void_t traits, the most concise SFINAE technique was a trailing decltype return type. The compiler evaluates the expression solely to determine whether it is well-formed; if it is not, the overload is silently dropped.

The trailing-return-type pattern

// Overload is viable only if x.serialize(os) is a valid expression
template <typename T>
auto write_to(std::ostream& os, const T& x)
    -> decltype(x.serialize(os), void())
{
    x.serialize(os);
}

The comma operator here is the key: (expr, void()) evaluates expr to trigger the SFINAE check, then discards its type in favour of void(). This prevents the overload from returning whatever expr happens to produce, while still gating visibility on whether expr is legal.

Constraining multiple expressions simultaneously

// Accept only types with both .begin() and .end()
template <typename Container>
auto print_range(const Container& c)
    -> decltype(c.begin(), c.end(), void())
{
    for (const auto& item : c) {
        std::cout << item << ' ';
    }
}

Chaining comma-separated expressions inside decltype(…, void()) makes all of them required — the first ill-formed expression triggers substitution failure for the whole overload.

Validating return-type shape

Trailing decltype also lets you constrain the shape of a return type, not just its existence:

// Accept T only if T::value_type is an arithmetic type
template <typename T>
auto sum(const T& container)
    -> std::enable_if_t<
           std::is_arithmetic_v<typename T::value_type>,
           typename T::value_type>
{
    typename T::value_type result{};
    for (const auto& v : container) result += v;
    return result;
}

std::enable_if Pitfalls: Immediate Context Rule

The most common SFINAE mistake is expecting failure inside a template body to silence an overload. SFINAE only applies during substitution — the phase where the compiler builds the function signature. Errors that occur after substitution, during instantiation of the body, are unconditional hard errors.

Substitution vs instantiation

template <typename T>
void call_serialize(T& x) {
    x.serialize();   // hard error if T has no serialize() — NOT a substitution failure
}

// This does NOT protect the overload:
template <typename T>
std::enable_if_t<true> call_serialize(T& x) {
    x.serialize();   // still a hard error at instantiation time
}

The enable_if in the return type fires during substitution of the return type. But x.serialize() is in the body, so the compiler does not see it until it instantiates the template for a specific T. At that point, substitution is over and SFINAE no longer applies.

What belongs in the immediate context

Only expressions constructed directly from the template parameters in the function signature participate in substitution failure. This includes:

• The return type (including trailing decltype)
• Template parameter declarations and their default arguments
• Function parameter types
• Exception specifications (noexcept(expr))

It does not include the function body, or errors that propagate from instantiating other templates invoked inside the signature (unless those templates are themselves well-formed but produce an invalid type that is then used).

The enable_if-in-function-body anti-pattern

// Does NOT work — enable_if is not in the signature
template <typename T>
void broken(T x) {
    typename std::enable_if<std::is_integral_v<T>>::type guard;  // hard error for non-integral T
    // …
}

// Correct — enable_if gates the signature itself
template <typename T, std::enable_if_t<std::is_integral_v<T>, int> = 0>
void correct(T x) {
    // body only reached for integral T
}

SFINAE vs Concepts (C++20)

C++20 concepts replace SFINAE for all new code targeting C++20 and above. The two mechanisms solve the same problem — constraining template instantiation — but with very different tradeoffs.

Error message quality

SFINAE failures produce errors at the call site that dump the entire substitution chain. For nested templates, these messages routinely exceed hundreds of lines. Concepts fail at the constraint check itself and name the unsatisfied requirement explicitly:

// SFINAE error excerpt (illustrative)
error: no matching function for call to 'serialize(Foo)'
note: candidate: template<class T, class> void serialize(T)
note: template argument deduction/substitution failed:
note: ... (20 more lines)

// Concepts error excerpt (illustrative)
error: constraints not satisfied for function 'serialize' [with T = Foo]
note: 'Foo' does not satisfy 'Serializable'
note: because 'declval<Foo>().serialize(declval<ostream&>())' would be ill-formed

Constraint subsumption

With enable_if, two overloads that have logically related but non-complementary constraints can produce ambiguity. Concepts support subsumption: a more-specific concept automatically wins over a less-specific one without requiring explicit mutual exclusion.

// SFINAE: must negate manually to avoid ambiguity
template <typename T, std::enable_if_t< std::is_integral_v<T>, int> = 0>
void process(T x);  // integral path

template <typename T, std::enable_if_t<!std::is_integral_v<T>, int> = 0>
void process(T x);  // fallback

// Concepts: subsumption handles the ordering automatically
template <std::integral T>
void process(T x);  // more specific — preferred when T is integral

template <typename T>
void process(T x);  // less specific — fallback for everything else

Migration table

When to keep SFINAE

• Targeting C++17 or earlier (concepts require C++20)
• Reading and maintaining existing library code that uses enable_if
• Conditional inclusion of class members, which concepts cannot yet express as cleanly
• Partial specialisation of class templates (concepts on class templates constrain instantiation but cannot partially specialise the same way enable_if can)

requires Expressions in C++20

C++20 requires expressions are the direct successor to expression SFINAE. They name four kinds of requirements, each catching a different class of constraint violations.

Simple requirements

A simple requirement is a bare expression statement. The compiler checks only that the expression is well-formed — it is not evaluated.

template <typename T>
concept Printable = requires(T v) {
    v.print();              // T must have a .print() member callable with no args
};

Compound requirements

A compound requirement additionally constrains the type (and optionally the noexcept status) of the expression's result:

template <typename T>
concept Serializable = requires(T v, std::ostream& os) {
    { v.serialize(os) } -> std::same_as<void>;      // must return void
    { v.byte_size() } -> std::convertible_to<std::size_t>;  // must be convertible to size_t
    { v.serialize(os) } noexcept;                   // must be noexcept
};

The braces wrap the expression; -> introduces the return-type constraint.

Type requirements

A type requirement checks that a nested name (type alias, member typedef, specialisation) is valid:

template <typename T>
concept Container = requires {
    typename T::value_type;
    typename T::iterator;
    typename std::iterator_traits<typename T::iterator>::difference_type;
};

Nested requirements

A nested requirement is a full requires clause embedded inside a requires expression, used to impose additional boolean constraints:

template <typename T>
concept SizedContainer = requires(T c) {
    { c.size() } -> std::convertible_to<std::size_t>;
    requires std::is_nothrow_move_constructible_v<T>;
    requires (sizeof(T) <= 64);   // size class constraint
};

Inline requires expressions vs named concepts

For one-off constraints, an ad-hoc requires expression in the function signature avoids the overhead of declaring a named concept:

// Inline — appropriate for a single-use constraint
template <typename T>
auto f(T x) requires requires { x.foo(); x.bar(); }
{
    return x.foo() + x.bar();
}

// Named concept — appropriate when the constraint is reused or part of an interface contract
template <typename T>
concept FooBar = requires(T x) {
    x.foo();
    x.bar();
};

template <FooBar T>
auto f(T x)
{
    return x.foo() + x.bar();
}

The doubled requires requires is not a typo: the first requires introduces the clause, the second starts the expression. Prefer named concepts when the constraint appears in more than one template, when it forms part of a public API contract, or when you want the concept name to appear in error messages.

See Also

• std::enable_if / std::enable_if_t (C++11/C++14) in <type_traits> — primary mechanism for SFINAE constraints
• std::void_t (C++17) in <type_traits> — maps any valid type sequence to void for detection
• std::declval (C++11) in <utility> — produces an unevaluated instance of a type for use inside decltype
• if constexpr (C++17) — preferred alternative to SFINAE for compile-time branching inside a function body
• C++20 concepts and requires clauses — the long-term replacement for SFINAE-based constraints; see std::derived_from, std::integral, and the full <concepts> header