skip to content

Two C++20 overloads constrained by `requires std::is_arithmetic_v<T>` and `requires std::is_arithmetic_v<T> && std::is_integral_v<T>` are ambiguous for int; why, and how do you fix it?

level: seniorimportance: should knowfreq 40%

answer

  1. the more constrained overload wins
  2. atomic constraints compared by identity
  3. same appearance in the source
  4. build stricter concepts from looser ones

basics

~20 s

Subsumption compares atomic constraints by identity, meaning the same expression from the same place in the source. Two separately written is_arithmetic_v<T> are different atomic constraints, so neither overload subsumes the other. Name the predicate as a concept and build the stricter one from it.

solid answer

~50 s

When two constrained templates are otherwise equally good, overload resolution picks the one whose constraints **subsume** the other's. To decide, the compiler normalizes each constraint: `&&` and `||` are kept as conjunction and disjunction, concept-ids are expanded into their definitions, and everything else becomes an **atomic constraint**. Atomic constraints match only if they come from the **same appearance** of the same expression in the source. In the question, each overload spells `std::is_arithmetic_v<T>` itself, so they are two different atomics, nothing subsumes, and the call is ambiguous; Apple clang 21 even notes `constraint expressions cannot be considered equivalent unless they originate from the same concept`. Fix: `concept Number = std::is_arithmetic_v<T>;` and `concept Exact = Number<T> && std::integral<T>;`. The standard's `std::signed_integral` (`integral<T> && is_signed_v<T>`) subsumes `std::integral` this way. Negation is atomic too, so `!Small<T>` written twice never matches.

code

cpp · 23 lines
cpp
#include <concepts>
#include <iostream>

template <class T> concept Number = std::integral<T> || std::floating_point<T>;

// std::integral<T> subsumes Number<T>: A subsumes (A || B).
template <class T> requires Number<T>        const char* f(T) { return "number"; }
template <class T> requires std::integral<T> const char* f(T) { return "integral"; }

// std::signed_integral is defined as integral<T> && is_signed_v<T>.
template <std::integral T>        const char* g(T) { return "integral"; }
template <std::signed_integral T> const char* g(T) { return "signed"; }

// A negation is one atomic constraint: name it once, as a concept.
template <class T> concept Small = sizeof(T) <= 2;
template <class T> concept Large = !Small<T>;
template <class T> requires Large<T>                     const char* k(T) { return "large"; }
template <class T> requires Large<T> && std::integral<T> const char* k(T) { return "large integral"; }

int main() {
    std::cout << f(1) << ' ' << f(1.0) << " | " << g(-3) << ' ' << g(3u)
              << " | " << k(1) << ' ' << k(1.0) << '\n';
}

go deeper

for a junior

Remember that when two constrained overloads both match, C++20 prefers the more constrained one, if the compiler can prove it.

for a middle

Explain normalization into conjunctions and disjunctions of atomic constraints and why concept-ids expand while traits do not.

for a senior

Diagnose ambiguous constrained overloads from the compiler note, restructure them into a concept hierarchy, and spot negations and variable templates that block subsumption.

for a principal

Own the concept hierarchy of a library as API: shallow, named refinements that callers' overloads can build on without ambiguity.

## Ordering overloads by constraints C++20 extends overload resolution with one more tie-breaker. If two candidates are equally good by the usual rules (same conversions, both templates, neither more specialized by partial ordering), the one whose constraints are **more constrained** wins. "More constrained" means its constraints **subsume** the other's: whenever the stricter one is satisfied, the looser one must be too, as the compiler can prove symbolically. The proof is not semantic. The compiler never reasons that `is_integral_v<T>` implies `is_arithmetic_v<T>`; it compares the **shape** of the constraints. ## Normal form and atomic constraints To compare constraints, each one is put into **normal form**: 1. `(E)` normalizes to the normal form of `E`. 2. `E1 && E2` becomes the **conjunction** of the two normal forms; `E1 || E2` becomes their **disjunction**. 3. A **concept-id** such as `Number<T>` is replaced by the normal form of the concept's definition, with its parameters mapped to the arguments. 4. **Anything else** is an **atomic constraint**: a trait like `std::is_integral_v<T>`, a comparison like `sizeof(T) > 4`, a requires-expression, and also a negation like `!Small<T>`. Two atomic constraints are **identical** only if they are formed from **the same appearance of the same expression** in the source, with equivalent parameter mappings. Then `P` subsumes `Q` if, roughly, every alternative way `P` can be satisfied contains every required piece of `Q`; for atomic `A` and `B`, `A && B` subsumes `A`, and `A` subsumes `A || B`. ## Why the raw traits are ambiguous ```cpp template <class T> requires std::is_arithmetic_v<T> const char* kind(T); template <class T> requires std::is_arithmetic_v<T> && std::is_integral_v<T> const char* kind(T); kind(1); // error: call to 'kind' is ambiguous ``` The text `std::is_arithmetic_v<T>` appears twice, in two places, so the two atomic constraints are different. The second overload's constraint is `X2 && Y` and the first is `X1`; `X2 && Y` does not contain `X1`, so neither subsumes. Apple clang 21 explains it in a note: `similar constraint expressions not considered equivalent; constraint expressions cannot be considered equivalent unless they originate from the same concept`. ## The fix and the standard library's own hierarchy Give each predicate **one appearance** by naming it as a concept, and build stricter concepts from looser ones: ```cpp template <class T> concept Number = std::integral<T> || std::floating_point<T>; template <class T> requires Number<T> const char* f(T); // "number" template <class T> requires std::integral<T> const char* f(T); // wins for int ``` Here `Number<T>` expands to `is_integral_v<T> || is_floating_point_v<T>`, using the very atomics inside `std::integral` and `std::floating_point`, and `std::integral<T>` alone subsumes that disjunction. The standard library is designed the same way: | Concept | Defined as | So it subsumes | |---|---|---| | `std::signed_integral<T>` | `integral<T> && is_signed_v<T>` | `std::integral<T>` | | `std::semiregular<T>` | `copyable<T> && default_initializable<T>` | both parts | | `std::regular<T>` | `semiregular<T> && equality_comparable<T>` | `std::semiregular<T>` | ## Traps - **Negation is atomic.** `requires (!Small<T>)` written in two overloads gives two different atomics; define `concept Large = !Small<T>;` and use `Large<T>` in both. - **`constexpr bool` variable templates are atomic.** A `template <class T> constexpr bool is_number = ...;` used in constraints never decomposes; only concepts are expanded. - **Ad-hoc requires-expressions are atomic.** Two `requires requires { ... }` clauses never order against each other, even if identical in text. - **Subsumption only breaks ties.** It applies when the candidates are otherwise equivalent; a better conversion sequence still wins first. - **Disjunctions are expensive to normalize** when concepts nest deeply, because normal forms can grow combinatorially; keep public concept hierarchies shallow. ## Reading an ambiguity report When two constrained overloads collide, work through it in order: 1. Confirm both candidates are satisfied for the argument; the compiler lists them as `candidate function [with T = int]`. 2. Write each constraint in normal form by expanding every concept-id it uses. 3. For each atomic constraint, ask where its text appears in the source. Two atomics only match if they trace back to one place, typically one line inside one concept definition. 4. If the stricter overload's normal form does not literally contain the looser one's atomics, introduce a concept for the shared predicate and rewrite both overloads in terms of it. ## A recipe for a numeric library Define the base predicates once (`Number`, `Exact`, `Approximate`), make every refinement a `&&` of an existing concept and one new requirement, and never repeat a raw trait in two constraints. Overloads for the general and the refined case then order themselves, without `int`/`long` tie-breakers or mutually exclusive `enable_if` conditions.

  • Does std::integral<T> subsume a concept defined as std::integral<T> || std::floating_point<T>?
    Yes. Normalization expands both into the atomic `is_integral_v<T>` from `std::integral`'s own definition, so they are identical atomics. A constraint `A` subsumes `A || B`, so an overload constrained by `std::integral<T>` is more constrained than one constrained by the disjunction and wins for `int`.
  • Why does subsumption not see through a constexpr bool variable template?
    Only concept-ids are expanded during normalization. A variable template such as `is_number<T>` is an ordinary expression, so it becomes one atomic constraint, and two of its uses in different places are different atomics. If a predicate should take part in overload ordering, it has to be a concept.
  • Is subsumption consulted when one candidate has a better conversion sequence?
    No. The usual ranking runs first: a candidate with a better implicit conversion for some argument wins regardless of constraints. Constraint ordering is the last tie-breaker, used only when the candidates are otherwise indistinguishable, for example two templates with identical parameter lists.

Job requirements written on two separate cards: a hiring panel compares the cards themselves, not what they mean, so 'any degree' and 'any degree plus a licence' only rank if the second card literally reuses the first card.

  • The compiler compares constraints by meaning, so equivalent traits subsume each other.
  • Two satisfied overloads with requires-clauses are always ambiguous.
  • Writing the same trait expression twice makes the two constraints identical.
  • Declaration order decides between two satisfied constrained overloads.
  • A negated concept like !Small<T> is expanded into the concept's own atomics.

Assumes C++20 or later: constraint normalization and subsumption ordering are C++20 rules.