# Conversion functions and explicit

> A class can convert from other types through converting constructors and to other types through conversion functions. The language applies at most one of these implicitly, and `explicit` removes a conversion from the implicit contexts without removing it from direct initialization.

- **Source:** C++ Atlas (https://cppatlas.com/topics/conversion-functions-and-explicit)
- **Track:** Classes
- **Estimated reading time:** 12 minutes
- **ISO C++ clauses:** [class.conv] (https://eel.is/c++draft/class.conv), [class.conv.general] (https://eel.is/c++draft/class.conv.general), [class.conv.ctor] (https://eel.is/c++draft/class.conv.ctor), [class.conv.fct] (https://eel.is/c++draft/class.conv.fct), [dcl.fct.spec] (https://eel.is/c++draft/dcl.fct.spec), [conv.general] (https://eel.is/c++draft/conv.general), [over.match.copy] (https://eel.is/c++draft/over.match.copy), [over.match.conv] (https://eel.is/c++draft/over.match.conv), [over.match.ctor] (https://eel.is/c++draft/over.match.ctor), [over.match.list] (https://eel.is/c++draft/over.match.list), [over.best.ics] (https://eel.is/c++draft/over.best.ics), [temp.deduct.conv] (https://eel.is/c++draft/temp.deduct.conv)
- **cppreference links:** [Converting constructor](https://en.cppreference.com/w/cpp/language/converting_constructor), [User-defined conversion function](https://en.cppreference.com/w/cpp/language/cast_operator), [explicit specifier](https://en.cppreference.com/w/cpp/language/explicit), [Copy-initialization](https://en.cppreference.com/w/cpp/language/copy_initialization), [Implicit conversions](https://en.cppreference.com/w/cpp/language/implicit_conversion)
- **Prerequisites:** implicit-conversions, initialization-forms, overload-resolution

## The one idea

A user-defined conversion is a function call the compiler inserts for you. There are two ways to write one. A **converting constructor** of `T` turns some other type into a `T`. A **conversion function** `operator U()` of `T` turns a `T` into a `U`. Either way, the compiler may insert at most one such call into an implicit conversion, surrounded by ordinary standard conversions.

`explicit` does not delete a conversion. It moves it out of the contexts where the compiler inserts conversions silently, mainly copy-initialization, and leaves it available where you asked for a `T` by name: direct-initialization, casts, and for `operator bool`, the conditions of `if` and loops.

> **Mental model.** An implicit conversion sequence is standard conversions, then at most one user-defined call, then standard conversions. `explicit` means "only when I write the target type myself".

## Converting constructors and conversion functions

Any constructor that is not `explicit` is a converting constructor, including ones with several parameters, which convert from braced lists. A conversion function is a member named `operator` followed by a type. It has no parameters and no declared return type, can be `const`, `virtual`, or a template, and since C++14 may be `operator auto()` with a deduced type.

Some conversion functions are never used implicitly. [class.conv.fct] says a conversion function is never used to convert an object to its own type, to a base class, or to `void`. Converting to a base is handled by the derived-to-base conversion, so the function would be dead code; GCC and Clang both warn with `-Wclass-conversion`.

Conversion functions are inherited like other members and may be virtual, so a call through a base reference can convert using the derived class's override. A conversion function in a derived class hides one in a base only when both convert to the same type; `operator long()` in the derived class leaves the base's `operator int()` visible.

`explicit` matters for constructors with several parameters too, because braced lists use them. With `explicit S(int, int)`, both `S s = {1, 2};` and `return {1, 2};` are ill-formed, while `S s{1, 2};` is fine.

```cpp
#include <cstdio>
struct B {};
struct D : B { operator B() const { std::puts("conv"); return {}; } };

void slice(D d) {
  B b = d;   // copies the B subobject; the conversion function is not called
  (void)b;
}
```

## The one-user-defined-conversion limit

[class.conv.general] says at most one user-defined conversion is implicitly applied to a single value. Standard conversions on either side do not count, so `int` to a class taking `double`, or a class with `operator long()` to `short`, are fine. Two class hops are not.

```cpp
#include <string>
struct Name { Name(std::string) {} };
void greet(Name);

void use() {
  // greet("bob");                // ill-formed: const char* -> std::string -> Name is two
  greet(std::string("bob"));      // OK: one user-defined conversion
  greet(Name("bob"));             // OK: the parameter of Name(std::string) gets the one hop
}
```

The limit is per value, not per expression. In `Name("bob")` the compiler is initializing the parameter of `Name`'s constructor, and that initialization may use its own conversion. The same is why `B b(1);` works when `B` has a constructor from `A` and `A` has a constructor from `int`, while `B b = 1;` does not: direct-initialization calls a `B` constructor whose parameter is converted from `1` in one hop, whereas copy-initialization needs one implicit conversion from `int` all the way to `B`.

The limit also shapes overload resolution. Two user-defined conversion sequences can be ranked against each other only when they use the same constructor or conversion function. If `f(A)` and `f(B)` both exist and `A` and `B` both have a constructor from `int`, then `f(1)` is ambiguous: each candidate needs a different user-defined conversion, and neither is better.

## Copy-initialization and direct-initialization pick from different sets

The two forms of initialization build different candidate sets, and most surprises come from that.

For `T t = u;` with `u` of another type, [over.match.copy] takes the converting constructors of `T` and the non-explicit conversion functions of `u`'s type that yield `T` or a derived class. Explicit constructors are not candidates at all, so a worse non-explicit one can win.

For `T t(u);`, [over.match.ctor] takes all constructors of `T`, explicit or not. The argument may then use a conversion function of `u` to reach a constructor's parameter type.

```cpp
#include <cstdio>
struct S {
  explicit S(int) { std::puts("int"); }
  S(double)       { std::puts("double"); }
};

int main() {
  S a = 1;   // prints double: S(int) is not a candidate
  S b(1);    // prints int
}
```

Copy-list-initialization is different again. For `S s = {1};`, [over.match.list] considers all constructors, explicit included, and if an explicit one wins, the program is ill-formed. It does not fall back to `S(double)`.

When the target is not a class, [over.match.conv] applies. Copy-initialization considers the non-explicit conversion functions that yield the target or something a standard conversion turns into it. Direct-initialization adds the explicit ones, but only those whose result reaches the target through at most a qualification conversion. An `explicit operator int()` therefore makes `int i(e);` well-formed and `long l(e);` ill-formed.

> **Standardese.** [over.match.conv] adds explicit conversion functions to the candidates only for direct-initialization, and only those yielding the target type or a type convertible to it by a qualification conversion. A promotion or integral conversion after an explicit conversion function is not allowed.

## Constructor versus conversion function

When both `A(const B&)` and `B::operator A() const` exist, copy-initializing an `A` from a `B` puts both in one candidate set. Both bind the `B` to a `const B&`, one as the constructor's parameter and one as the implicit object parameter, so neither is better and the conversion is ambiguous.

```cpp
struct B;
struct A { A() = default; A(const B&); };
struct B { operator A() const; };

// A a = B{};   // ill-formed: ambiguous between A(const B&) and B::operator A
```

Clang rejects this. GCC 16 accepts it by default as an extension and calls the constructor, and diagnoses the ambiguity under `-pedantic-errors`. Do not rely on the extension. Direct-initialization `A a(B{});` is not ambiguous, because only constructors of `A` are candidates, and `A(const B&)` beats `A(A&&)`, which would need the conversion function as a user-defined conversion. Small changes tip the balance: if `operator A()` is not `const`, it wins copy-initialization outright, because binding the non-const implicit object parameter is better than binding `const B&`.

> **Pitfall.** Providing a conversion in both directions, or in both classes, is almost always a mistake. Pick one owner for each conversion.

## explicit, explicit(bool), and contextual conversion to bool

Before C++11, a class that wanted to be testable in `if (p)` had to convert to something, and `operator bool()` let it be added to integers, compared with unrelated classes, and passed to `int` parameters. The safe-bool idiom worked around this by converting to a pointer to member, which could be tested but not used in arithmetic. C++11 replaced it with `explicit operator bool`.

An explicit conversion to `bool` is used only where the language **contextually converts to bool**: the conditions of `if`, `while`, `for` and `do`, the operands of `!`, `&&` and `||`, the first operand of `?:`, `static_assert`, and `noexcept(expr)`. It is also used by direct-initialization of a `bool`. It is not used for `bool b = f;`, for `return f;` in a function returning `bool`, or for `f == true`.

```cpp
struct F { explicit operator bool() const { return true; } };

bool test(F f) {
  if (f) {}             // OK: contextual
  bool a = !f;          // OK: contextual
  bool b(f);            // OK: direct-initialization
  // bool c = f;        // ill-formed: copy-initialization
  // int  i(f);         // ill-formed: bool -> int is not a qualification conversion
  return a || b;        // OK; plain "return f;" would be ill-formed
}
```

C++20 added `explicit(bool)`, whose operand is a constant expression of type `bool`, typically one that depends on template parameters. It lets one constructor template be implicit exactly when the underlying conversion is, which is how `std::pair` and `std::optional` became conditionally explicit without duplicated overloads.

```cpp
#include <string>
#include <type_traits>

template<class T> struct Wrap {
  T v;
  template<class U>
  explicit(!std::is_convertible_v<U, T>) Wrap(U&& u) : v(static_cast<U&&>(u)) {}
};

Wrap<std::string> a = "hi";                     // OK: const char* converts implicitly
Wrap<std::string> b(std::string_view("hi"));    // OK: direct-initialization
// Wrap<std::string> c = std::string_view("hi"); // ill-formed: explicit here
```

Mark single-argument constructors and conversion functions `explicit` by default. The exceptions are types meant to be interchangeable with their source, like `std::string` from `const char*`.

## Conversion function templates

A conversion function may be a template. Its template arguments are deduced from the type the conversion is needed for, not from any argument. [temp.deduct.conv] strips references and top-level cv-qualifiers from that required type before deducing, so converting to `const int&` deduces `int`.

```cpp
struct Any {
  template<class T> operator T() const { return T{}; }
};

int i = Any{};          // T = int
const int& r = Any{};   // T = int, and r binds to a temporary
double d = Any{};       // T = double
```

Such a type converts to everything, which makes it useful for test doubles and for proxy objects, and dangerous in overload sets, where it makes every overload viable. Constrain the template, for example with a concept, to keep it from matching by accident.

## What to remember

- An implicit conversion contains at most one user-defined conversion, with standard conversions allowed before and after.
- A conversion function to the class itself, a base, or `void` is never used implicitly.
- Copy-initialization excludes explicit constructors from the candidates; copy-list-initialization includes them and is ill-formed if one wins.
- Direct-initialization considers explicit constructors, and explicit conversion functions followed by at most a qualification conversion.
- `explicit operator bool` works in conditions, `!`, `&&`, `||`, `?:` and `static_assert`, but not in `return`, `==` or `bool b = f;`.
- A converting constructor and a matching `const` conversion function make copy-initialization ambiguous; GCC accepts it only as an extension.
- `explicit(bool)` (C++20) makes a constructor conditionally explicit.
- Conversion function templates deduce from the target type with references and top-level cv removed.

## Concept Map Outline

- **Conversion functions and explicit:** User-defined conversions in both directions, at most one per implicit conversion.
  - **Two directions:** A constructor converts into the class; operator U() converts out of it.
    - **Converting constructor:** Any non-explicit constructor, including multi-parameter ones used by braced lists.
    - **Conversion function:** No parameters, no declared return type; may be const, virtual, a template or operator auto.
    - **Never used implicitly:** Conversion to the class itself, a base class, or void is never applied implicitly.
  - **One-conversion limit:** At most one user-defined conversion is applied implicitly to a single value.
    - **Standard conversions around:** Promotions or conversions may come before and after the one user-defined call.
    - **Two hops fail:** const char* to std::string to Name is two user-defined conversions, so it fails.
    - **Per value:** Direct-initialization converts a constructor's argument separately, so B b(1) can work where B b = 1 fails.
  - **Candidate sets:** The form of initialization decides which functions are even considered.
    - **Copy-initialization:** Converting constructors plus non-explicit conversion functions; explicit ones are not candidates.
    - **Direct-initialization:** All constructors, plus explicit conversion functions followed by at most a qualification conversion.
    - **Copy-list-initialization:** Explicit constructors are candidates, and choosing one makes it ill-formed.
    - **Ctor versus conv function:** A(const B&) and B::operator A() const make A a = B{} ambiguous.
  - **explicit operator bool:** C++11 replacement for the safe-bool idiom.
    - **Contextual contexts:** if, while, for, do, !, &&, ||, the first operand of ?:, static_assert and noexcept(expr).
    - **Not contextual:** bool b = f, return f, f == true and int i(f) are all ill-formed.
    - **Safe-bool history:** Before C++11, classes converted to a member pointer so they were testable but not arithmetic.
  - **explicit(bool):** C++20: a constant bool decides whether the constructor is explicit.
    - **Conditionally explicit:** explicit(!is_convertible_v<U, T>) makes a wrapper exactly as implicit as T.
    - **Library use:** std::pair and std::optional constructors are conditionally explicit this way.
  - **Conversion templates:** template<class T> operator T() deduces T from the required target type.
    - **Deduction rule:** References and top-level cv are stripped, so const int& deduces int.
    - **Converts to anything:** Makes every overload viable; constrain it to avoid accidental matches.

## Standardese Quiz Questions

### Question 1 [warmup] ([over.match.copy], [over.match.ctor], [class.conv.ctor])

What does this program print?

```cpp
#include <cstdio>

struct S {
  explicit S(int) { std::puts("int"); }
  S(double)       { std::puts("double"); }
};

int main() {
  S a = 1;
  S b(1);
  (void)a; (void)b;
}
```

A. `int` then `int`
B. Nothing: `S a = 1;` is ill-formed because the best constructor is explicit
C. `double` then `int`
D. `double` then `double`

**Answer (C):** `double` then `int`

**Why:** In copy-initialization from a non-class type, only converting constructors are candidates, and an explicit constructor is not a converting constructor. So `S a = 1;` calls `S(double)` after converting `1`, and direct-initialization `S b(1);` considers every constructor and picks the exact match `S(int)`. The second option describes copy-list-initialization, `S a = {1};`, which does consider explicit constructors and is ill-formed if one wins.

### Question 2 [warmup] ([class.conv.general], [over.best.ics])

Is the call in `main` well-formed?

```cpp
#include <string>

struct Name { Name(std::string) {} };
void greet(Name) {}

int main() { greet("bob"); }
```

A. Ill-formed: it needs two user-defined conversions
B. Well-formed: `const char*` converts to `std::string`, which converts to `Name`
C. Well-formed, because the first conversion is a standard library one
D. Ill-formed: string literals cannot initialize class parameters

**Answer (A):** Ill-formed: it needs two user-defined conversions

**Why:** An implicit conversion sequence may contain at most one user-defined conversion. Turning `const char*` into `std::string` is one, through a constructor, and turning `std::string` into `Name` is a second, so no viable conversion exists. Library types get no special treatment, which rules out the third option. `greet(std::string("bob"))` or `greet(Name("bob"))` each need only one implicit hop and are fine.

### Question 3 [warmup] ([class.conv.fct], [conv.general], [over.match.conv])

Given `struct F { explicit operator bool() const; };` and `F f;`, which of these is ill-formed?

A. `if (f) {}`
B. `bool a = !f;`
C. `bool b(f);`
D. `bool c = f;`

**Answer (D):** `bool c = f;`

**Why:** An explicit conversion function is used only by direct-initialization and by contexts that contextually convert to `bool`. The `if` condition and the operand of `!` are contextual conversions, and `bool b(f);` is direct-initialization, so all three work. `bool c = f;` is copy-initialization, which does not consider explicit conversion functions; `return f;` from a function returning `bool` fails for the same reason.

### Question 4 [tricky] ([over.match.list], [dcl.init.list])

Is this declaration well-formed?

```cpp
struct S {
  explicit S(int) {}
  S(double) {}
};

S s = {1};
```

A. Well-formed: it calls `S(double)`, as `S s = 1;` would
B. Ill-formed: `S(int)` is selected and it is explicit
C. Ill-formed: narrowing from `int` to `double` in a braced list
D. Well-formed: it calls `S(int)`, because braces allow explicit constructors

**Answer (B):** Ill-formed: `S(int)` is selected and it is explicit

**Why:** Copy-list-initialization considers all constructors, including explicit ones, and [over.match.list] says that if an explicit constructor is chosen, the initialization is ill-formed. `S(int)` is the exact match, so it wins and then fails. This differs from `S s = 1;`, where explicit constructors are not candidates and `S(double)` is called. There is no narrowing issue because `S(double)` is not selected, and `1` to `double` would not narrow anyway, since the constant fits exactly.

### Question 5 [tricky] ([over.match.copy], [over.ics.rank], [over.match.best])

Under the C++23 standard, is the declaration of `a` well-formed?

```cpp
struct B;
struct A { A() = default; A(const B&); };
struct B { operator A() const; };

A a = B{};
```

A. Well-formed: constructors are always preferred over conversion functions
B. Well-formed: guaranteed elision makes the conversion function the better match
C. Implementation-defined
D. Ill-formed: the conversion is ambiguous

**Answer (D):** Ill-formed: the conversion is ambiguous

**Why:** Copy-initialization of `A` from a `B` makes both `A(const B&)` and `B::operator A() const` candidates. Each binds the `B` prvalue to a `const B&`, one as the constructor parameter and one as the implicit object parameter, so the conversion sequences are indistinguishable and no tie-breaker applies. Clang reports the ambiguity; GCC 16 accepts it by default as an extension and calls the constructor, which is where the first option comes from, but rejects it with `-pedantic-errors`.

### Question 6 [tricky] ([class.conv.fct], [dcl.init.general])

What does this program print?

```cpp
#include <cstdio>

struct B {};
struct D : B {
  operator B() const { std::puts("conv"); return {}; }
};

int main() {
  D d;
  B b = d;
  (void)b;
  std::puts("done");
}
```

A. `conv` then `done`
B. `done`
C. Nothing: the program is ill-formed because the conversion is ambiguous
D. Either output; it is unspecified which conversion is used

**Answer (B):** `done`

**Why:** A conversion function is never used to convert an object to its own type or to a base class; that job belongs to the derived-to-base conversion. So `B b = d;` binds `B`'s copy constructor to the `B` subobject of `d` and the conversion function is not a candidate. Calling `d.operator B()` explicitly would still work, which is why the declaration is legal, and compilers warn with `-Wclass-conversion`.

### Question 7 [standardese] ([over.match.conv], [expr.static.cast], [dcl.init.general])

Which declaration in `use` is ill-formed?

```cpp
struct E { explicit operator int() const { return 4; } };

void use(E e) {
  int a(e);                   // #1
  int b = static_cast<int>(e); // #2
  long c(e);                  // #3
}
```

A. #1 only: explicit conversion functions need a cast
B. #3 only
C. #1 and #3
D. None of them

**Answer (B):** #3 only

**Why:** For direct-initialization of a non-class type, [over.match.conv] adds explicit conversion functions to the candidates, but only those whose result reaches the target type by at most a qualification conversion. #1 and #2 (a static_cast is defined as a direct-initialization) target `int` exactly. #3 would need an integral conversion from `int` to `long` after the explicit function, which is not allowed, so there is no viable conversion. The same rule makes `int i(f);` ill-formed for an `explicit operator bool`.

### Question 8 [standardese] ([temp.deduct.conv], [over.match.ref], [dcl.init.ref])

For the initialization of `r`, what is `T` deduced as?

```cpp
struct Any {
  template<class T> operator T() const { return T{}; }
};

const int& r = Any{};
```

A. `const int&`
B. `const int`
C. `int`
D. Deduction fails, so the program is ill-formed

**Answer (C):** `int`

**Why:** A conversion function template deduces `T` from the type required as the result of the conversion. [temp.deduct.conv] uses the referred-to type when that type is a reference, and then ignores its top-level cv-qualifiers, so `const int&` becomes `const int` and then `int`. The conversion returns an `int` prvalue, which is materialized as a temporary and bound to `r`, with its lifetime extended.
