C++ FAQ / Section 10 / FAQ 10.22

 E-mail the author
[ Subject index | About the author | © ]
Revised Jul 4, 2012

[10.22] What is the purpose of the explicit keyword?

To tell the compiler that a certain constructor may not be used to implicitly cast an expression to its class type.

The explicit keyword is an optional decoration for constructors that take exactly one argument. It only applies to single-argument constructors since those are the only constructors that can be used in type casting.

For example, without the explicit keyword the following code is valid:

class Foo {
public:
  Foo(int x);
};

class Bar {
public:
  Bar(double x);
};

void yourCode()
{
  Foo a = 42;         //OK: calls Foo::Foo(int) passing 42 as an argument
  Foo b(42);          //OK: calls Foo::Foo(int) passing 42 as an argument
  Foo c = Foo(42);    //OK: calls Foo::Foo(int) passing 42 as an argument
  Foo d = (Foo)42;    //OK: calls Foo::Foo(int) passing 42 as an argument

  Bar x = 3.14;       //OK: calls Bar::Bar(double) passing 3.14 as an argument
  Bar y(3.14);        //OK: calls Bar::Bar(double) passing 3.14 as an argument
  Bar z = Bar(3.14);  //OK: calls Bar::Bar(double) passing 3.14 as an argument
  Bar w = (Bar)3.14;  //OK: calls Bar::Bar(double) passing 3.14 as an argument
}

But sometimes you want to prevent this sort of implicit promotion or implicit type conversion. For example, if Foo is really an array-like container and 42 is the initial size, you might want to let your users say, Foo x(42); or perhaps Foo x = Foo(42);, but not just Foo x = 42;. If that's the case, you should use the explicit keyword:

class Foo {
public:
  explicit Foo(int x);
};

class Bar {
public:
  explicit Bar(double x);
};

void yourCode()
{
  Foo a = 42;         //Compile-time error: can't convert 42 to an object of type Foo
  Foo b(42);          //OK: calls Foo::Foo(int) passing 42 as an argument
  Foo c = Foo(42);    //OK: calls Foo::Foo(int) passing 42 as an argument
  Foo d = (Foo)42;    //OK: calls Foo::Foo(int) passing 42 as an argument

  Bar x = 3.14;       //Compile-time error: can't convert 3.14 to an object of type Bar
  Bar y(3.14);        //OK: calls Bar::Bar(double) passing 3.14 as an argument
  Bar z = Bar(3.14);  //OK: calls Bar::Bar(double) passing 3.14 as an argument
  Bar w = (Bar)3.14;  //OK: calls Bar::Bar(double) passing 3.14 as an argument
}

You can mix explicit constructors and non-explicit constructors in the same class. For example, this class has an explicit constructor taking a bool but a non-explicit constructor taking a double:

#include <iostream>

class Foo {
public:
  Foo(double x)        { std::cout << "Foo(double)\n"; }
  explicit Foo(bool x) { std::cout << "Foo(bool)\n"; }
};

void yourCode()
{
  Foo a = true;       //OK: implicitly promotes true to (double)1.0, then calls Foo::Foo(double)
  Foo b = Foo(true);  //OK: explicitly calls Foo::Foo(bool)
}

The above code will print the following:

Foo(double)
Foo(bool)

Variable a is initialized using the Foo(double) constructor because Foo(bool) cannot be used in an implicit cast, but true can be interpreted as a (double)true, that is, as 1.0, and implicitly cast to Foo using Foo::Foo(double). This may or may not be what you intended, but this is what happens.