A consteval function is a function that must evaluate at compile-time. Consteval functions otherwise follow the same rules as constexpr functions.

Quiz time

Question #1

Add const and/or constexpr to the following program:

#include <iostream>

// gets tower height from user and returns it
double getTowerHeight()
{
	std::cout << "Enter the height of the tower in meters: ";
	double towerHeight{};
	std::cin >> towerHeight;
	return towerHeight;
}

// Returns ball height from ground after "seconds" seconds
double calculateBallHeight(double towerHeight, int seconds)
{
	double gravity{ 9.8 };

	// Using formula: [ s = u * t + (a * t^2) / 2 ], here u(initial velocity) = 0
	double distanceFallen{ (gravity * (seconds * seconds)) / 2.0 };
	double currentHeight{ towerHeight - distanceFallen };

	return currentHeight;
}

// Prints ball height above ground
void printBallHeight(double ballHeight, int seconds)
{
	if (ballHeight > 0.0)
		std::cout << "At " << seconds << " seconds, the ball is at height: " << ballHeight << " meters\n";
	else
		std::cout << "At " << seconds << " seconds, the ball is on the ground.\n";
}

// Calculates the current ball height and then prints it
// This is a helper function to make it easier to do this
void printCalculatedBallHeight(double towerHeight, int seconds)
{
	double ballHeight{ calculateBallHeight(towerHeight, seconds) };
	printBallHeight(ballHeight, seconds);
}

int main()
{
	double towerHeight{ getTowerHeight() };

	printCalculatedBallHeight(towerHeight, 0);
	printCalculatedBallHeight(towerHeight, 1);
	printCalculatedBallHeight(towerHeight, 2);
	printCalculatedBallHeight(towerHeight, 3);
	printCalculatedBallHeight(towerHeight, 4);
	printCalculatedBallHeight(towerHeight, 5);

	return 0;
}

Show Solution

#include <iostream>

// This function should not be made constexpr because output and input can only be done at runtime.
// The versions of `operator<<` and `operator>>` that do output and input don't support constexpr.
double getTowerHeight()
{
	std::cout << "Enter the height of the tower in meters: ";
	double towerHeight{};
	std::cin >> towerHeight;
	return towerHeight;
}

// Returns height from ground after "seconds" seconds
// This function is made constepxr because it just calculates a value from its inputs and return it.
// Arithmetic can be done at compile-time, and no non-constexpr functions are called.
// Reminder: A constexpr function can be evaluated at compile-time or runtime.
//   If its arguments are constexpr, it can be called at compile-time.
//   In this case, it's called at runtime because the argument for towerHeight isn't constexpr.
// If a function can be made constexpr, it should be.
// Remember: function parameters are not constexpr, even in a constexpr function
constexpr double calculateBallHeight(double towerHeight, int seconds)
{
	constexpr double gravity{ 9.8 }; // constexpr because it's a compile-time constant

	// Using formula: [ s = u * t + (a * t^2) / 2 ], here u(initial velocity) = 0
	// These variables can't be constexpr since their initializers aren't constant expressions
	const double distanceFallen{ (gravity * (seconds * seconds)) / 2.0 };
	const double currentHeight{ towerHeight - distanceFallen };

	return currentHeight;
}

// This function should not be made constexpr because output and input can only be done at runtime.
// The versions of `operator<<` and `operator>>` that do output and input don't support constexpr.
void printBallHeight(double ballHeight, int seconds)
{
	if (ballHeight > 0.0)
		std::cout << "At " << seconds << " seconds, the ball is at height: " << ballHeight << " meters\n";
	else
		std::cout << "At " << seconds << " seconds, the ball is on the ground.\n";
}

// This function should not be made constexpr because output and input can only be done at runtime.
// The versions of `operator<<` and `operator>>` that do output and input don't support constexpr.
void printCalculatedBallHeight(double towerHeight, int seconds)
{
	// height can only be const (not constexpr) because its initializer is not a constant expression
	const double ballHeight{ calculateBallHeight(towerHeight, seconds) };
	printBallHeight(ballHeight, seconds);
}

int main()
{
	// towerHeight can only be const (not constexpr) because its initializer is not a constant expression
	const double towerHeight{ getTowerHeight() };

	printCalculatedBallHeight(towerHeight, 0);
	printCalculatedBallHeight(towerHeight, 1);
	printCalculatedBallHeight(towerHeight, 2);
	printCalculatedBallHeight(towerHeight, 3);
	printCalculatedBallHeight(towerHeight, 4);
	printCalculatedBallHeight(towerHeight, 5);

	return 0;
}

Within a constexpr or consteval function, we can use local variables that are not constexpr, and the value of these variables can be changed.

As a silly example:

#include <iostream>

consteval int doSomething(int x, int y) // function is consteval
{
    x = x + 2;       // we can modify the value of non-const function parameters

    int z { x + y }; // we can instantiate non-const local variables
    if (x > y)
        z = z - 1;   // and then modify their values

    return z;
}

int main()
{
    constexpr int g { doSomething(5, 6) };
    std::cout << g << '\n';

    return 0;
}

When such functions are evaluated at compile-time, the compiler will essentially “execute” the function and return the calculated value.

Constexpr/consteval functions can use function parameters and local variables as arguments in constexpr function calls

Above, we noted, “When a constexpr (or consteval) function is being evaluated at compile-time, any other functions it calls are required to be evaluated at compile-time.”

Perhaps surprisingly, a constexpr or consteval function can use its function parameters (which aren’t constexpr) or even local variables (which may not be const at all) as arguments in a constexpr function call. When a constexpr or consteval function is being evaluated at compile-time, the value of all function parameters and local variables must be known to the compiler (otherwise it couldn’t evaluate them at compile-time). Therefore, in this specific context, C++ allows these values to be used as arguments in a call to a constexpr function, and that constexpr function call can still be evaluated at compile-time.

#include <iostream>

constexpr int goo(int c) // goo() is now constexpr
{
    return c;
}

constexpr int foo(int b) // b is not a constant expression within foo()
{
    return goo(b);       // if foo() is resolved at compile-time, then `goo(b)` can also be resolved at compile-time
}

int main()
{
    std::cout << foo(5);
    
    return 0;
}

In the above example, foo(5) may or may not be evaluated at compile time. If it is, then the compiler knows that b is 5. And even though b is not constexpr, the compiler can treat the call to goo(b) as if it were goo(5) and evaluate that function call at compile-time. If foo(5) is instead resolved at runtime, then goo(b) will also be resolved at runtime.

Can a constexpr function call a non-constexpr function?

The answer is yes, but only when the constexpr function is being evaluated in a non-constant context. A non-constexpr function may not be called when a constexpr function is evaluating in a constant context (because then the constexpr function wouldn’t be able to produce a compile-time constant value), and doing so will produce a compilation error.

Calling a non-constexpr function is allowed so that a constexpr function can do something like this:

#include <type_traits> // for std::is_constant_evaluated

constexpr int someFunction()
{
    if (std::is_constant_evaluated()) // if evaluating in constant context
        return someConstexprFcn();
    else
        return someNonConstexprFcn();
}

Now consider this variant:

constexpr int someFunction(bool b)
{
    if (b)
        return someConstexprFcn();
    else
        return someNonConstexprFcn();
}

This is legal as long as someFunction(false) is never called in a constant expression.

For best results, we’d advise the following:

1. Avoid calling non-constexpr functions from within a constexpr function if possible.
2. If your constexpr function requires different behavior for constant and non-constant contexts, conditionalize the behavior with if (std::is_constant_evaluated()) (in C++20) or if consteval (C++23 onward).
3. Always test your constexpr functions in a constant context, as they may work when called in a non-constant context but fail in a constant context.

When should I constexpr a function?

As a general rule, if a function can be evaluated as part of a required constant expression, it should be made constexpr.

A pure function is a function that meets the following criteria:

• The function always returns the same return result when given the same arguments
• The function has no side effects (e.g. it doesn’t change the value of static local or global variables, doesn’t do input or output, etc…).

Pure functions should generally be made constexpr.

That said, if your program is trivial or a throw-away and you don’t constexpr a function, the world isn’t going to end. Hopefully.

Why not constexpr every function?

There are a few reasons you may not want to constexpr a function:

1. constexpr signals that a function can be used in a constant expression. If your function cannot be evaluated as part of a constant expression, it should not be marked as constexpr.
2. constexpr is part of the interface of a function. Once a function is made constexpr, it can be called by other constexpr functions or used in contexts that require constant expressions. Removing the constexpr later will break such code.
3. constexpr makes functions harder to debug because you can’t inspect them at runtime.

Why constexpr a function when it is not actually evaluated at compile-time?

New programmers sometimes ask, “why should I constexpr a function when it is only evaluated at runtime in my program (e.g. because the arguments in the function call are non-const)”?

There are a few reasons:

1. There’s little downside to using constexpr, and it may help the compiler optimize your program to be smaller and faster.
2. Just because you’re not calling the function in a compile-time evaluatable context right now doesn’t mean you won’t call it in such a context when you modify or extend your program. And if you haven’t constexpr’d the function already, you may not think to when you do start to call it in such a context, and then you’ll miss out on the performance benefits. Or you may be forced to constexpr it later when you need to use the return value in a context that requires a constant expression somewhere.
3. Repetition helps ingrain best practices.

On a non-trivial project, it’s a good idea to implement your functions with the mindset that they may be reused (or extended) in the future. Any time you modify an existing function, you risk breaking it, and that means it needs to be retested, which takes time and energy. It’s often worth spending an extra minute or two “doing it right the first time” so you don’t have to redo (and retest) it again later.

There is no way to tell the compiler that a constexpr function should prefer to evaluate at compile-time whenever it can (e.g. in cases where the return value of a constexpr function is used in a non-constant expression).

However, we can force a constexpr function that is eligible to be evaluated at compile-time to actually evaluate at compile-time by ensuring the return value is used where a constant expression is required. This needs to be done on a per-call basis.

The most common way to do this is to use the return value to initialize a constexpr variable (this is why we’ve been using variable ‘g’ in prior examples). Unfortunately, this requires introducing a new variable into our program just to ensure compile-time evaluation, which is ugly and reduces code readability.

However, in C++20, there is a better workaround to this issue, which we’ll present in a moment.

Consteval C++20

C++20 introduces the keyword consteval, which is used to indicate that a function must evaluate at compile-time, otherwise a compile error will result. Such functions are called immediate functions.

#include <iostream>

consteval int greater(int x, int y) // function is now consteval
{
    return (x > y ? x : y);
}

int main()
{
    constexpr int g { greater(5, 6) };              // ok: will evaluate at compile-time
    std::cout << g << '\n';

    std::cout << greater(5, 6) << " is greater!\n"; // ok: will evaluate at compile-time

    int x{ 5 }; // not constexpr
    std::cout << greater(x, 6) << " is greater!\n"; // error: consteval functions must evaluate at compile-time

    return 0;
}

In the above example, the first two calls to greater() will evaluate at compile-time. The call to greater(x, 6) cannot be evaluated at compile-time, so a compile error will result.

Perhaps surprisingly, the parameters of a consteval function are not constexpr (even though consteval functions can only be evaluated at compile-time). This decision was made for the sake of consistency.

Using consteval to make constexpr execute at compile-time C++20

The downside of consteval functions is that such functions can’t evaluate at runtime, making them less flexible than constexpr functions, which can do either. Therefore, it would still be useful to have a convenient way to force constexpr functions to evaluate at compile-time (even when the return value is being used where a constant expression is not required), so that we could have compile-time evaluation when possible, and runtime evaluation when we can’t.

Consteval functions provides a way to make this happen, using a neat helper function:

#include <iostream>

// Uses abbreviated function template (C++20) and `auto` return type to make this function work with any type of value
// See 'related content' box below for more info (you don't need to know how these work to use this function)
consteval auto compileTimeEval(auto value)
{
    return value;
}

constexpr int greater(int x, int y) // function is constexpr
{
    return (x > y ? x : y);
}

int main()
{
    std::cout << greater(5, 6) << '\n';                  // may or may not execute at compile-time
    std::cout << compileTimeEval(greater(5, 6)) << '\n'; // will execute at compile-time

    int x { 5 };
    std::cout << greater(x, 6) << '\n';                  // we can still call the constexpr version at runtime if we wish

    return 0;
}

This works because consteval functions require constant expressions as arguments -- therefore, if we use the return value of a constexpr function as an argument to a consteval function, the constexpr function must be evaluated at compile-time! The consteval function just returns this argument as its own return value, so the caller can still use it.

Note that the consteval function returns by value. While this might be inefficient to do at runtime (if the value was some type that is expensive to copy, e.g. std::string), in a compile-time context, it doesn’t matter because the entire call to the consteval function will simply be replaced with the calculated return value.

Determining if a constexpr function call is evaluating at compile-time or runtime

C++ does not currently provide any reliable mechanisms to do this.

What about std::is_constant_evaluated or if consteval? Advanced

Neither of these capabilities tell you whether a function call is evaluating at compile-time or runtime.

std::is_constant_evaluated() (defined in the <type_traits> header) returns a bool indicating whether the current function is executing in a constant-evaluated context. A constant-evaluated context (also called a constant context) is defined as one in which a constant expression is required (such as the initialization of a constexpr variable). So in cases where the compiler is required to evaluate a constant expression at compile-time std::is_constant_evaluated() will true as expected.

This is intended to allow you to do something like this:

#include <type_traits> // for std::is_constant_evaluated()

constexpr int someFunction()
{
    if (std::is_constant_evaluated()) // if evaluating in constant context
        doSomething();
    else
        doSomethingElse();
}

However, the compiler may also choose to evaluate a constexpr function at compile-time in a context that does not require a constant expression. In such cases, std::is_constant_evaluated() will return false even though the function did evaluate at compile-time. So std::is_constant_evaluated() really means “the compiler is being forced to evaluate this at compile-time”, not “this is evaluating at compile-time”.

Introduced in C++23, if consteval is a replacement for if (std::is_constant_evaluated()) that provides a nicer syntax and fixes some other issues. However, it evaluates the same way.

You might expect that a constexpr function would evaluate at compile-time whenever possible, but unfortunately this is not the case.

In lesson 5.5 -- Constant expressions, we noted that in contexts that do not require a constant expression, the compiler may choose whether to evaluate a constant expression at either compile-time or at runtime. Accordingly, any constexpr function call that is part of a non-required constant expression may be evaluated at either compile-time or runtime.

For example:

#include <iostream>

constexpr int getValue(int x)
{
    return x;
}

int main()
{
    int x { getValue(5) }; // may evaluate at runtime or compile-time
    
    return 0;
}

In the above example, because getValue() is constexpr, the call getValue(5) is a constant expression. However, because variable x is not constexpr, it does not require a constant expression initializer. So even though we’ve provided a constant expression initializer, the compiler is free to choose whether getValue(5) evaluates at runtime or compile-time.

Diagnosis of constexpr functions in required constant expressions

The compiler is not required to determine whether a constexpr function is evaluatable at compile-time until it is actually evaluated at compile-time. It is fairly easy to write a constexpr function that compiles successfully for runtime use, but then fails to compile when evaluated at compile-time.

As a silly example of this:

#include <iostream>

int getValue(int x)
{
    return x;
}

// This function can be evaluated at runtime
// When evaluated at compile-time, the function will produce a compilation error
// because the call to getValue(x) cannot be resolved at compile-time
constexpr int foo(int x)
{
    if (x < 0) return 0; // needed prior to adoption of P2448R1 in C++23 (see note below)
    return getValue(x);  // call to non-constexpr function here
}

int main()
{
    int x { foo(5) };           // okay: will evaluate at runtime
    constexpr int y { foo(5) }; // compile error: foo(5) can't evaluate at compile-time

    return 0;
}

In the above example, when foo(5) is used as an initializer for non-constexpr variable x, it will be evaluated at runtime. This works fine, and returns the value 5.

However, when foo(5), is used as an initializer for constexpr variable y, it must be evaluated at compile-time. At that point, the compiler will determine that the call to foo(5) can’t be evaluated at compile-time, as getValue() is not a constexpr function.

Therefore, when writing a constexpr function, always explicitly test that it compiles when evaluated at compile-time (by calling it in a context where a constant expression is required, such as in the initialization of a constexpr variable).

Constexpr/consteval function parameters are not constexpr

The parameters of a constexpr function are not implicitly constexpr, nor may they be declared as constexpr.

Because such parameters are not constexpr, they cannot be used in constant expressions within the function.

consteval int goo(int c)    // c is not constexpr, and cannot be used in constant expressions
{
    return c;
}

constexpr int foo(int b)    // b is not constexpr, and cannot be used in constant expressions
{
    constexpr int b2 { b }; // compile error: constexpr variable requires constant expression initializer

    return goo(b);          // compile error: consteval function call requires constant expression argument
}

int main()
{
    constexpr int a { 5 };

    std::cout << foo(a); // okay: constant expression a can be used as argument to constexpr function foo()
    
    return 0;
}

In the above example, function parameter b is not constexpr (even though argument a is a constant expression). This means b cannot be used anywhere a constant expression is required, such as the the initializer for a constexpr variable (e.g. b2) or in a call to a consteval function (goo(b)).

The parameters of constexpr functions may be declared as const, in which case they are treated as runtime constants.

Constexpr functions are implicitly inline

When a constexpr function is evaluated at compile-time, the compiler must be able to see the full definition of the constexpr function prior to such function calls (so it can perform the evaluation itself). A forward declaration will not suffice in this case, even if the actual function definition appears later in the same compilation unit.

This means that a constexpr function called in multiple files needs to have its definition included into each translation unit -- which would normally be a violation of the one-definition rule. To avoid such problems, constexpr functions are implicitly inline, which makes them exempt from the one-definition rule.

As a result, constexpr functions are often defined in header files, so they can be #included into any .cpp file that requires the full definition.

For constexpr function calls that are only evaluated at runtime, a forward declaration is sufficient to satisfy the compiler. This means you can use a forward declaration to call a constexpr function defined in another translation unit, but only if you invoke it in a context that does not require compile-time evaluation.

#include <iostream>

constexpr int foo(int);

constexpr int goo(int c)
{
	return foo(c);   // note that foo is not defined yet
}

constexpr int foo(int b) // okay because foo is still defined before any calls to goo
{
	return b;
}

int main()
{
	 constexpr int a{ goo(5) }; // this is the outermost invocation

	return 0;
}

Recap

Marking a function as constexpr means it can be used in a constant expression. It does not mean “will evaluate at compile-time”.

A constant expression (which may contain constexpr function calls) is only required to evaluate at compile-time in contexts where a constant expression is required.

In contexts that do not require a constant expression, the compiler may choose whether to evaluate a constant expression (which may contain constexpr function calls) at compile-time or at runtime.

A runtime (non-constant) expression (which may contain constexpr function calls or non-constexpr function calls) will evaluate at runtime.

Another example

Let’s do another examine to explore how a constexpr function is required or likely to evaluate further:

#include <iostream>

constexpr int greater(int x, int y)
{
    return (x > y ? x : y);
}

int main()
{
    constexpr int g { greater(5, 6) };              // case 1: always evaluated at compile-time
    std::cout << g << " is greater!\n";

    std::cout << greater(5, 6) << " is greater!\n"; // case 2: may be evaluated at either runtime or compile-time

    int x{ 5 }; // not constexpr but value is known at compile-time
    std::cout << greater(x, 6) << " is greater!\n"; // case 3: likely evaluated at runtime

    std::cin >> x;
    std::cout << greater(x, 6) << " is greater!\n"; // case 4: always evaluated at runtime

    return 0;
}

In case 1, we’re calling greater() in a context that requires a constant expression. Thus greater() must be evaluated at compile-time.

In case 2, the greater() function is being called in a context that does not require a constant expression, as output statements must execute at runtime. However, since the arguments are constant expressions, the function is eligible to be evaluated at compile-time. Thus the compiler is free to choose whether this call to greater() will be evaluated at compile-time or runtime.

In case 3, we’re calling greater() with one argument that is not a constant expression. So this will typically execute at runtime.

However, this argument has a value that is known at compile-time. Under the as-if rule, the compiler could decide to treat the evaluation of x as a constant expression, and evaluate this call to greater() at compile-time. But more likely, it will evaluate it at runtime.

In case 4, the value of argument x can’t be known at compile-time, so this call to greater() will always evaluate at runtime.

Note that your compiler’s optimization level setting may have an impact on whether it decides to evaluate a function at compile-time or runtime. This also means that your compiler may make different choices for debug vs. release builds (as debug builds typically have optimizations turned off).

For example, both gcc and Clang will not compile-time evaluate a constexpr function called where a constant expression isn’t required unless the compiler told to optimize the code (e.g. using the -O2 compiler option).

In programming, optimization is the process of modifying software to make it work more efficiently (e.g. to run faster, or use fewer resources). Optimization can have a huge impact on the overall performance level of an application.

Some types of optimization are typically done by hand. A program called a profiler can be used to see how long various parts of the program are taking to run, and which are impacting overall performance. The programmer can then look for ways to alleviate those performance issues. Because hand-optimization is slow, programmers typically focuses on making high-level improvements that will have a large impact (such as choosing more performant algorithms, optimizing data storage and access, reducing resource utilization, parallelizing tasks, etc…)

Other kinds of optimization can be performed automatically. A program that optimizes another program is called an optimizer. Optimizers typically work at a low-level, looking for ways to improve statements or expressions by rewriting, reordering, or eliminating them. For example, when you write i = i * 2;, the optimizer might rewrite this as i *= 2;, i += i;, or i <<= 1;. For integral values, all of these produce the same result, but one might be faster than the others on a given architecture. A programmer would probably not know which is the most performant choice (and the answer might vary based on architecture), but an optimizer for a given system would. Individual low-level optimizations may only yield small performance gains, but their cumulative effect can result in a significant performance improvement overall.

Modern C++ compilers are optimizing compilers, meaning they are capable of automatically optimizing your programs as part of the compilation process. Just like the preprocessor, these optimizations do not modify your source code files -- rather, they are applied transparently as part of the compilation process.

Because optimization involves some tradeoffs (we’ll discuss this at the bottom of the lesson), compilers typically support multiple optimization levels that determine whether they optimize, how aggressively they optimize, and what kind of optimizations they prioritize (e.g. speed vs size).

Most compilers default to no optimization, so if you’re using a command-line compiler, you’ll need to enable optimization yourself. If you’re using an IDE, the IDE will likely automatically configure release builds to enable optimization and debug builds to disable optimization.

The as-if rule

In C++, compilers are given a lot of leeway to optimize programs. The as-if rule says that the compiler can modify a program however it likes in order to produce more optimized code, so long as those modifications do not affect a program’s “observable behavior”.

Modern compilers employ a variety of different techniques in order to optimize a program effectively. Which techniques can be applied depends on the program and the quality of the compiler and optimizer.

An optimization opportunity

Consider the following short program:

#include <iostream>

int main()
{
	int x { 3 + 4 };
	std::cout << x << '\n';

	return 0;
}

The output is straightforward:

7

However, there’s an interesting optimization possibility hidden within.

If this program were compiled exactly as it was written (with no optimizations), the compiler would generate an executable that calculates the result of 3 + 4 at runtime (when the program is run). If the program were executed a million times, 3 + 4 would be evaluated a million times, and the resulting value of 7 produced a million times.

Because the result of 3 + 4 never changes (it is always 7), re-calculating this result every time the program is run is wasteful.

Compile-time evaluation

Modern C++ compilers are capable of fully or partially evaluating certain expressions at compile-time (rather than at runtime). When the compiler fully or partially evaluates an expression at compile-time, this is called compile-time evaluation.

For illustrative purposes, in this lesson we will look at some simple optimization techniques that make use of compile-time evaluation. Then, we’ll continue our discussion of compile-time evaluation in subsequent lessons.

Constant folding

One of the original forms of compile-time evaluation is called “constant folding”. Constant folding is an optimization technique where the compiler replaces expressions that have literal operands with the result of the expression. Using constant folding, the compiler would recognize that the expression 3 + 4 has constant operands, and then replace the expression with the result 7.

The result would be equivalent to the following:

#include <iostream>

int main()
{
	int x { 7 };
	std::cout << x << '\n';

	return 0;
}

This program produces the same output (7) as the prior version, but the resulting executable no longer needs to spend CPU cycles calculating 3 + 4 at runtime!

Constant folding can also be applied to subexpressions, even when the full expression must execute at runtime.

#include <iostream>

int main()
{
	std::cout << 3 + 4 << '\n';

	return 0;
}

In the above example, 3 + 4 is a subexpression of the full expression std::cout << 3 + 4 << '\n';. The compiler can optimize this to std::cout << 7 << '\n';.

Constant propagation

The following program contains another optimization opportunity:

#include <iostream>

int main()
{
	int x { 7 };
	std::cout << x << '\n';

	return 0;
}

When x is initialized, the value 7 will be stored in the memory allocated for x. Then on the next line, the program will go out to memory again to fetch the value 7 so it can be printed. This requires two memory access operations (one to store the value, and one to fetch it).

Constant propagation is an optimization technique where the compiler replaces variables known to have constant values with their values. Using constant propagation, the compiler would realize that x always has the constant value 7, and replace any use of variable x with the value 7.

The result would be equivalent to the following:

#include <iostream>

int main()
{
	int x { 7 };
	std::cout << 7 << '\n';

	return 0;
}

This removes the need for the program to go out to memory to fetch the value of x.

Constant propagation may produce a result that can then be optimized by constant folding:

#include <iostream>

int main()
{
	int x { 7 };
	int y { 3 };
	std::cout << x + y << '\n';

	return 0;
}

In this example, constant propagation would transform x + y into 7 + 3, which can then be constant folded into the value 10.

Dead code elimination

Dead code elimination is an optimization technique where the compiler removes code that may be executed but has no effect on the program’s behavior.

Back to a prior example:

#include <iostream>

int main()
{
	int x { 7 };
	std::cout << 7 << '\n';

	return 0;
}

In this program, variable x is defined and initialized, but it is never used anywhere, so it has no effect on the program’s behavior. Dead code elimination would remove the definition of x.

The result would be equivalent to the following:

#include <iostream>

int main()
{
	std::cout << 7 << '\n';

	return 0;
}

When a variable is removed from a program because it is no longer needed, we say the variable has been optimized out (or optimized away).

Compared to the original version, this optimized version no longer requires runtime calculation expression 3 + 4, nor does it require two memory access operations (one to initialize variable x and one to read the value from x). This means the program will be both smaller and faster.

Const variables are easier to optimize

In some cases, there are simple things we can do to help the compiler optimize more effectively.

Constant propagation can be challenging for the compiler. In the section on constant propagation, we offered this example:

#include <iostream>

int main()
{
	int x { 7 };
	std::cout << x << '\n';

	return 0;
}

Since x is defined as a non-const variable, in order to apply this optimization, the compiler must realize that the value of x actually doesn’t change (even though it could). Whether the compiler is capable of doing so comes down to how complex the program is and how sophisticated the compiler’s optimization routines are.

We can help the compiler optimize more effectively by using constant variables wherever possible. For example:

#include <iostream>

int main()
{
	const int x { 7 }; // x is now const
	std::cout << x << '\n';

	return 0;
}

Because x is now const, the compiler has a guarantee that x can’t be changed after initialization. This makes it more likely the compiler will apply constant propagation, and then optimize the variable out entirely.

Optimization can make programs harder to debug

If optimization makes our programs faster, why isn’t it turned on by default?

When the compiler optimizes a program, the result is that variables, expressions, statements, and function calls may be rearranged, modified, replaced, or removed entirely. Such changes can make it hard to debug a program effectively.

At runtime, it can be hard to debug compiled code that no longer correlates very well with the original source code. For example, if you try to watch a variable that has been optimized out, the debugger won’t be able to locate the variable. If you try to step into a function that has been optimized away, the debugger will simply skip over it. So if you are debugging your code and the debugger is behaving strangely, this is the most likely reason.

At compile-time, we have little visibility and few tools to help us understand what the compiler is even doing. If a variable or expression is replaced with a value, and that value is wrong, how do we even go about debugging the issue? This is an ongoing challenge.

To help minimize such issues, debug builds will typically leave optimizations turned off, so that the compiled code will more closely match the source code.

Nomenclature: Compile-time constants vs runtime constants

Constants in C++ are sometimes divided into two informal categories.

A compile-time constant is a constant whose value is known at compile-time. Examples include:

• Literals.
• Constant objects whose initializers are compile-time constants.

A runtime constant is a constant whose value is determined in a runtime context. Examples include:

• Constant function parameters.
• Constant objects whose initializers are non-constants or runtime constants.

For example:

#include <iostream>

int five()
{
    return 5;
}

int pass(const int x) // x is a runtime constant
{
    return x;
}

int main()
{
    // The following are non-constants:
    [[maybe_unused]] int a { 5 };

    // The following are compile-time constants:
    [[maybe_unused]] const int b { 5 };
    [[maybe_unused]] const double c { 1.2 };
    [[maybe_unused]] const int d { b };       // b is a compile-time constant

    // The following are runtime constants:
    [[maybe_unused]] const int e { a };       // a is non-const
    [[maybe_unused]] const int f { e };       // e is a runtime constant
    [[maybe_unused]] const int g { five() };  // return value isn't known until runtime
    [[maybe_unused]] const int h { pass(5) }; // return value isn't known until runtime

    return 0;
}

Although you will encounter these terms out in the wild, in C++ these definitions are not all that useful:

• Some runtime constants (and even non-constants) can be evaluated at compile-time for optimization purposes (under the as-if rule).
• Some compile-time constants (e.g. const double d { 1.2 };) cannot be used in compile-time features (as defined by the language standard). We’ll discuss this more in lesson 5.5 -- Constant expressions.

For this reason, we recommend avoiding these terms. We’ll discuss the nomenclature that you should use instead in the next lesson.

main.cpp:

#include <iostream>

template <typename T>
T addOne(T x); // function template forward declaration

int main()
{
    std::cout << addOne(1) << '\n';
    std::cout << addOne(2.3) << '\n';

    return 0;
}

add.cpp:

template <typename T>
T addOne(T x) // function template definition
{
    return x + 1;
}

If addOne were a non-template function, this program would work fine: In main.cpp, the compiler would be satisfied with the forward declaration of addOne, and the linker would connect the call to addOne() in main.cpp to the function definition in add.cpp.

But because addOne is a template, this program doesn’t work, and we get a linker error:

1>Project6.obj : error LNK2019: unresolved external symbol "int __cdecl addOne<int>(int)" (??$addOne@H@@YAHH@Z) referenced in function _main
1>Project6.obj : error LNK2019: unresolved external symbol "double __cdecl addOne<double>(double)" (??$addOne@N@@YANN@Z) referenced in function _main

In main.cpp, we call addOne<int> and addOne<double>. However, since the compiler can’t see the definition for function template addOne, it can’t instantiate those functions inside main.cpp. It does see the forward declaration for addOne though, and will assume those functions exist elsewhere and will be linked in later.

When the compiler goes to compile add.cpp, it will see the definition for function template addOne. However, there are no uses of this template in add.cpp, so the compiler will not instantiate anything. The end result is that the linker is unable to connect the calls to addOne<int> and addOne<double> in main.cpp to the actual functions, because those functions were never instantiated.

The most conventional way to address this issue is to put all your template code in a header (.h) file instead of a source (.cpp) file:

add.h:

#ifndef ADD_H
#define ADD_H

template <typename T>
T addOne(T x) // function template definition
{
    return x + 1;
}

#endif

main.cpp:

#include "add.h" // import the function template definition
#include <iostream>

int main()
{
    std::cout << addOne(1) << '\n';
    std::cout << addOne(2.3) << '\n';

    return 0;
}

That way, any files that need access to the template can #include the relevant header, and the template definition will be copied by the preprocessor into the source file. The compiler will then be able to instantiate any functions that are needed.

You may be wondering why this doesn’t cause a violation of the one-definition rule (ODR). The ODR says that types, templates, inline functions, and inline variables are allowed to have identical definitions in different files. So there is no problem if the template definition is copied into multiple files (as long as each definition is identical).

But what about the instantiated functions themselves? If a function is instantiated in multiple files, how does that not cause a violation of the ODR? The answer is that functions implicitly instantiated from templates are implicitly inline. And as you know, inline functions can be defined in multiple files, so long as the definition is identical in each.

Here’s another example of a function template being placed in a header file, so it can be included into multiple source files:

max.h:

#ifndef MAX_H
#define MAX_H

template <typename T>
T max(T x, T y)
{
    return (x < y) ? y : x;
}

#endif

foo.cpp:

#include "max.h" // import template definition for max<T>(T, T)
#include <iostream>

void foo()
{
	std::cout << max(3, 2) << '\n';
}

main.cpp:

#include "max.h" // import template definition for max<T>(T, T)
#include <iostream>

void foo(); // forward declaration for function foo

int main()
{
    std::cout << max(3, 5) << '\n';
    foo();

    return 0;
}

In the above example, both main.cpp and foo.cpp #include "max.h" so the code in both files can make use of the max<T>(T, T) function template.

#include <iostream>

constexpr int greater(int x, int y)
{
    return (x > y ? x : y);
}

int main()
{
    std::cout << greater(5, 6) << '\n'; // greater(5, 6) may be evaluated at compile-time or runtime

    constexpr int g { greater(5, 6) };  // greater(5, 6) must be evaluated at compile-time
    std::cout << g << '\n';             // prints 6

    return 0;
}

In this example, greater() is a constexpr function, and greater(5, 6) is a constant expression, which may be evaluated at either compile-time or runtime. Because std::cout << greater(5, 6) calls greater(5, 6) in a non-constexpr context, the compiler is free to choose whether to evaluate greater(5, 6) at compile-time or runtime. When greater(5, 6) is used to initialize constexpr variable g, greater(5, 6) is called in a constexpr context, and must be evaluated at compile-time.

Now consider the following similar example:

#include <iostream>

struct Pair
{
    int m_x {};
    int m_y {};

    int greater() const
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

int main()
{
    Pair p { 5, 6 };                  // inputs are constexpr values
    std::cout << p.greater() << '\n'; // p.greater() evaluates at runtime

    constexpr int g { p.greater() };  // compile error: greater() not constexpr
    std::cout << g << '\n';

    return 0;
}

In this version, we have an aggregate struct named Pair, and greater() is now a member function. However, because member function greater() is not constexpr, p.greater() is not a constant expression. When std::cout << p.greater() calls p.greater() (in a non-constexpr context), p.greater() will be evaluated at runtime. However, when we try to use p.greater() to initialize constexpr variable g, we get a compile error, as p.greater() cannot be evaluated at compile-time.

Since the inputs to p are constexpr values (5 and 6), it seems like p.greater() should be capable of being evaluated at compile-time. But how do we do that?

Constexpr member functions

Just like non-member functions, member functions can be made constexpr via use of the constexpr keyword. Constexpr member functions can be evaluated at either compile-time or runtime.

#include <iostream>

struct Pair
{
    int m_x {};
    int m_y {};

    constexpr int greater() const // can evaluate at either compile-time or runtime
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

int main()
{
    Pair p { 5, 6 };
    std::cout << p.greater() << '\n'; // okay: p.greater() evaluates at runtime

    constexpr int g { p.greater() };  // compile error: p not constexpr
    std::cout << g << '\n';

    return 0;
}

In this example, we’ve made greater() a constexpr function, so the compiler can evaluate it at either runtime or compile-time.

When we call p.greater() in runtime expression std::cout << p.greater(), it evaluates at runtime.

However, when p.greater() is used to initialize constexpr variable g, we get a compiler error. Although greater() is now constexpr, p is still not constexpr, therefore p.greater() is not a constant expression.

Constexpr aggregates

Okay, so if we need p to be constexpr, let’s just make it constexpr:

#include <iostream>

struct Pair // Pair is an aggregate
{
    int m_x {};
    int m_y {};

    constexpr int greater() const
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

int main()
{
    constexpr Pair p { 5, 6 };        // now constexpr
    std::cout << p.greater() << '\n'; // p.greater() evaluates at runtime or compile-time

    constexpr int g { p.greater() };  // p.greater() must evaluate at compile-time
    std::cout << g << '\n';

    return 0;
}

Since Pair is an aggregate, and aggregates implicitly support constexpr, we’re done. This works! Since p is a constexpr type, and greater() is a constexpr member function, p.greater() is a constant expression and can be used in places where only constant expressions are allowed.

Constexpr class objects and constexpr constructors

Now let’s make our Pair a non-aggregate:

#include <iostream>

class Pair // Pair is no longer an aggregate
{
private:
    int m_x {};
    int m_y {};

public:
    Pair(int x, int y): m_x { x }, m_y { y } {}

    constexpr int greater() const
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

int main()
{
    constexpr Pair p { 5, 6 };       // compile error: p is not a literal type
    std::cout << p.greater() << '\n';

    constexpr int g { p.greater() };
    std::cout << g << '\n';

    return 0;
}

This example is almost identical to the prior one, except Pair is no longer an aggregate (due to having private data members and a constructor).

When we compile this program, we get a compiler error about Pair not being a “literal type”. Say what?

In C++, a literal type is any type for which it might be possible to create an object within a constant expression. Put another way, an object can’t be constexpr unless the type qualifies as a literal type. And our non-aggregate Pair does not qualify.

The definition of a literal type is complex, and a summary can be found on cppreference. However, it’s worth noting that literal types include:

• Scalar types (those holding a single value, such as fundamental types and pointers)
• Reference types
• Most aggregates
• Classes that have a constexpr constructor

And now we see why our Pair isn’t a literal type. When a class object is instantiated, the compiler will call the constructor function to initialize the object. And the constructor function in our Pair class is not constexpr, so it can’t be invoked at compile-time. Therefore, Pair objects cannot be constexpr.

The fix for this is simple: we just make our constructor constexpr as well:

#include <iostream>

class Pair
{
private:
    int m_x {};
    int m_y {};

public:
    constexpr Pair(int x, int y): m_x { x }, m_y { y } {} // now constexpr

    constexpr int greater() const
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

int main()
{
    constexpr Pair p { 5, 6 };
    std::cout << p.greater() << '\n';

    constexpr int g { p.greater() };
    std::cout << g << '\n';

    return 0;
}

This works as expected, just like our aggregate version of Pair did.

Implicitly defined constructors are constexpr if they can be defined as such. Explicitly defaulted constructors must be explicitly defined as constexpr.

Constexpr members may be needed with non-constexpr/non-const objects

In the above example, since the initializer of constexpr variable g must be a constant expression, it’s clear that p.greater() must be a constant expression, and therefore p, the Pair constructor, and greater() must all be constexpr.

However, if we replace p.greater() with a constexpr function, things get a little less obvious:

#include <iostream>

class Pair
{
private:
    int m_x {};
    int m_y {};

public:
    constexpr Pair(int x, int y): m_x { x }, m_y { y } {}

    constexpr int greater() const
    {
        return (m_x > m_y  ? m_x : m_y);
    }
};

constexpr int init()
{
    Pair p { 5, 6 };    // requires constructor to be constexpr when evaluated at compile-time
    return p.greater(); // requires greater() to be constexpr when evaluated at compile-time
}

int main()
{
    constexpr int g { init() }; // init() evaluated in compile-time context
    std::cout << g << '\n';

    return 0;
}

Remember that a constexpr function can evaluate at either runtime or compile-time. And when a constexpr function evaluates at compile-time, it can only call functions capable of evaluating at compile-time. In the case of a class type, that means constexpr member functions.

Since g is constexpr, init() must be evaluated at compile-time. Within the init() function, we define p as non-constexpr/non-const (because we can, not because we should). Even though p is not defined as constexpr, p still needs to be created at compile-time, and therefore requires a constexpr Pair constructor. Similarly, in order for p.greater() to evaluate at compile-time, greater() must be a constexpr member function. If either the Pair constructor or greater() were not constexpr, the compiler would error.

Constexpr member functions may be const or non-const C++14

In C++11, non-static constexpr member functions are implicitly const (except constructors).

However, as of C++14, constexpr member functions are no longer implicitly const. This means that if you want a constexpr function to be a const function, you must explicitly mark it as such.

Constexpr non-const member functions can change data members Optional

A constexpr non-const member function can change data members of the class, so long as the implicit object isn’t const. This is true even if the function is evaluating at compile-time.

Here’s a contrived example of this:

#include <iostream>

class Pair
{
private:
    int m_x {};
    int m_y {};

public:
    constexpr Pair(int x, int y): m_x { x }, m_y { y } {}

    constexpr int greater() const // constexpr and const
    {
        return (m_x > m_y  ? m_x : m_y);
    }

    constexpr void reset() // constexpr but non-const
    {
        m_x = m_y = 0; // non-const member function can change members
    }

    constexpr const int& getX() const { return m_x; }
};

// This function is constexpr
constexpr Pair zero()
{
    Pair p { 1, 2 }; // p is non-const
    p.reset();       // okay to call non-const member function on non-const object
    return p;
}

int main()
{
    Pair p1 { 3, 4 };
    p1.reset();                     // okay to call non-const member function on non-const object
    std::cout << p1.getX() << '\n'; // prints 0
    
    Pair p2 { zero() };             // zero() will be evaluated at runtime
    p2.reset();                     // okay to call non-const member function on non-const object
    std::cout << p2.getX() << '\n'; // prints 0

    constexpr Pair p3 { zero() };   // zero() will be evaluated at compile-time
//    p3.reset();                   // Compile error: can't call non-const member function on const object
    std::cout << p3.getX() << '\n'; // prints 0

    return 0;
}

As we work through this example, remember:

• A non-const member function can modify members of non-const objects.
• A constexpr member function can be called in either runtime contexts or compile-time contexts.

These two things work independently.

In the case of p1, p1 is non-const. Therefore, we are allowed to call non-const member function p1.reset() to modify p1. The fact that reset() is constexpr doesn’t matter here because nothing we’re doing requires compile-time evaluation.

The p2 case is similar. In this case, the initializer to p2 is a function call to zero(). Even though zero() is a constexpr function, in this case it is invoked in a runtime context, and acts just like a normal function. Within zero(), we instantiate non-const p, call non-const member function p.reset() on it, and then return p. The returned Pair is used as the initializer for p2. The fact that zero() and reset() are constexpr don’t matter in this case, because nothing we’re doing requires compile-time evaluation.

The p3 case is the interesting one. Because p3 is constexpr, it must have a constant expression initializer. Therefore, this call to zero() must evaluate at compile-time. And because we’re evaluating in a compile-time context, we can only call constexpr functions. Inside zero(), p is non-const (which is allowed, even though we’re evaluating at compile-time). However, because we’re in a compile-time context, the constructor used to create p must be constexpr. And just like the p2 case, we’re allowed to call non-const member function p.reset() on non-const object p. But because we’re in a compile-time context, the reset() member function must be constexpr. The function then returns p, which is used to initialize p3.

Constexpr functions that return const references (or pointers) Optional

Normally you won’t see constexpr and const used right next to each other, but one case where this does happen is when you have a constexpr member function that returns a const reference (or (const) pointer-to-const).

In our Pair class above, getX() is a constexpr member function that returns a const reference:

    constexpr const int& getX() const { return m_x; }

That’s a lot of const-ing!

The constexpr indicates that the member function can be evaluated at compile-time. The const int& is the return type of the function. The rightmost const means the member-function itself is const so it can be called on const objects.

constexpr const int* const getXPtr() const { return &m_x; }

PrintStandard.cpp:

// This program prints the C++ language standard your compiler is currently using
// Freely redistributable, courtesy of learncpp.com (https://www.learncpp.com/cpp-tutorial/what-language-standard-is-my-compiler-using/)

#include <iostream>

const int numStandards = 7;
// The C++26 stdCode is a placeholder since the exact code won't be determined until the standard is finalized
const long stdCode[numStandards] = { 199711L, 201103L, 201402L, 201703L, 202002L, 202302L, 202612L};
const char* stdName[numStandards] = { "Pre-C++11", "C++11", "C++14", "C++17", "C++20", "C++23", "C++26" };

long getCPPStandard()
{
    // Visual Studio is non-conforming in support for __cplusplus (unless you set a specific compiler flag, which you probably haven't)
    // In Visual Studio 2015 or newer we can use _MSVC_LANG instead
    // See https://devblogs.microsoft.com/cppblog/msvc-now-correctly-reports-__cplusplus/
#if defined (_MSVC_LANG)
    return _MSVC_LANG;
#elif defined (_MSC_VER)
    // If we're using an older version of Visual Studio, bail out
    return -1;
#else
    // __cplusplus is the intended way to query the language standard code (as defined by the language standards)
    return __cplusplus;
#endif
}

int main()
{
    long standard = getCPPStandard();

    if (standard == -1)
    {
        std::cout << "Error: Unable to determine your language standard.  Sorry.\n";
        return 0;
    }
    
    for (int i = 0; i < numStandards; ++i)
    {
        // If the reported version is one of the finalized standard codes
        // then we know exactly what version the compiler is running
        if (standard == stdCode[i])
        {
            std::cout << "Your compiler is using " << stdName[i]
                << " (language standard code " << standard << "L)\n";
            break;
        }

        // If the reported version is between two finalized standard codes,
        // this must be a preview / experimental support for the next upcoming version.
        if (standard < stdCode[i])
        {
            std::cout << "Your compiler is using a preview/pre-release of " << stdName[i]
                << " (language standard code " << standard << "L)\n";
            break;
        }
    }
    
    return 0;
}

Build or runtime issues

If you get an error while trying to build this, you may have your project set up incorrectly. See 0.8 -- A few common C++ problems for advice on some common issues. If that does not help, review the lessons starting from 0.6 -- Installing an Integrated Development Environment (IDE).

If the program prints “Error: Unable to determine your language standard”, your compiler may be non-conforming. If you are using a popular compiler and this is the case, please leave a comment below with relevant information (e.g. the name and version of your compiler).

If this program prints a different language standard than you were expecting:

• Check your IDE settings to ensure your compiler is configured to use the language standard you expect. See 0.12 -- Configuring your compiler: Choosing a language standard for more information on how to do this for some of the major compilers. Make sure there are no typos or formatting errors. Some compilers require setting the language standard for each project rather than globally, so if you’ve just created a new project, this may be the case.

• Your IDE or compiler may not even be reading the configuration file you’re editing (we see occasionally reader feedback on this with VS Code). If this seems like the case, please consult documentation for your IDE or compiler.

#include <iostream>
#include <string_view>

enum Color
{
    black,
    red,
    blue,
};

constexpr std::string_view getColorName(Color color)
{
    switch (color)
    {
    case black: return "black";
    case red:   return "red";
    case blue:  return "blue";
    default:    return "???";
    }
}

int main()
{
    constexpr Color shirt{ blue };

    std::cout << "Your shirt is " << getColorName(shirt) << '\n';

    return 0;
}

Although the above example works just fine, there are two downsides:

1. We have to remember the name of the function we created to get the enumerator name.
2. Having to call such a function adds clutter to our output statement.

Ideally, it would be nice if we could somehow teach operator<< to output an enumeration, so we could do something like this: std::cout << shirt and have it do what we expect.

Introduction to operator overloading

In lesson 11.1 -- Introduction to function overloading, we introduced function overloading, which allows us to create multiple functions with the same name so long as each function has a unique function prototype. Using function overloading, we can create variations of a function that work with different data types, without having to think up a unique name for each variant.

Similarly, C++ also supports operator overloading, which lets us define overloads of existing operators, so that we can make those operators work with our program-defined data types.

Basic operator overloading is fairly straightforward:

• Define a function using the name of the operator as the function’s name.
• Add a parameter of the appropriate type for each operand (in left-to-right order). One of these parameters must be a user-defined type (a class type or an enumerated type), otherwise the compiler will error.
• Set the return type to whatever type makes sense.
• Use a return statement to return the result of the operation.

When the compiler encounters the use of an operator in an expression and one or more of the operands is a user-defined type, the compiler will check to see if there is an overloaded operator function that it can use to resolve that call. For example, given some expression x + y, the compiler will use function overload resolution to see if there is an operator+(x, y) function call that it can use to evaluate the operation. If a non-ambiguous operator+ function can be found, it will be called, and the result of the operation returned as the return value.

Overloading operator<< to print an enumerator

Before we proceed, let’s quickly recap how operator<< works when used for output.

Consider a simple expression like std::cout << 5. std::cout has type std::ostream (which is a user-defined type in the standard library), and 5 is a literal of type int.

When this expression is evaluated, the compiler will look for an overloaded operator<< function that can handle arguments of type std::ostream and int. It will find such a function (also defined as part of the standard I/O library) and call it. Inside that function, std::cout is used to output x to the console (exactly how is implementation-defined). Finally, the operator<< function returns its left-operand (which in this case is std::cout), so that subsequent calls to operator<< can be chained.

With the above in mind, let’s implement an overload of operator<< to print a Color:

#include <iostream>
#include <string_view>

enum Color
{
	black,
	red,
	blue,
};

constexpr std::string_view getColorName(Color color)
{
    switch (color)
    {
    case black: return "black";
    case red:   return "red";
    case blue:  return "blue";
    default:    return "???";
    }
}

// Teach operator<< how to print a Color
// std::ostream is the type of std::cout, std::cerr, etc...
// The return type and parameter type are references (to prevent copies from being made)
std::ostream& operator<<(std::ostream& out, Color color)
{
    out << getColorName(color); // print our color's name to whatever output stream out 
    return out;                 // operator<< conventionally returns its left operand

    // The above can be condensed to the following single line:
    // return out << getColorName(color)
}

int main()
{
	Color shirt{ blue };
	std::cout << "Your shirt is " << shirt << '\n'; // it works!

	return 0;
}

This prints:

Your shirt is blue

Let’s unpack our overloaded operator function a bit. First, the name of the function is operator<<, since that is the name of the operator we’re overloading. operator<< has two parameters. The left parameter (which will be matched with the left operand) is our output stream, which has type std::ostream. We use pass by non-const reference here because we don’t want to make a copy of a std::ostream object when the function is called, but the std::ostream object needs to be modified in order to do output. The right parameter (which will be matched with the right operand) is our Color object. Since operator<< conventionally returns its left operand, the return type matches the type of the left-operand, which is std::ostream&.

Now let’s look at the implementation. A std::ostream object already knows how to print a std::string_view using operator<< (this comes as part of the standard library). So out << getColorName(color) simply fetches our color’s name as a std::string_view and then prints it to the output stream.

Note that our implementation uses parameter out instead of std::cout because we want to allow the caller to determine which output stream they will output to (e.g. std::cerr << color should output to std::cerr, not std::cout).

Returning the left operand is also easy. The left operand is parameter out, so we just return out.

Putting it all together: when we call std::cout << shirt, the compiler will see that we’ve overloaded operator<< to work with objects of type Color. Our overloaded operator<< function is then called with std::cout as the out parameter, and our shirt variable (which has value blue) as parameter color. Since out is a reference to std::cout, and color is a copy of enumerator blue, the expression out << getColorName(color) prints "blue" to the console. Finally out is returned back to the caller in case we want to chain additional output.

Overloading operator>> to input an enumerator

Similar to how we were able to teach operator<< to output an enumeration above, we can also teach operator>> how to input an enumeration:

#include <iostream>
#include <limits>
#include <optional>
#include <string>
#include <string_view>

enum Pet
{
    cat,   // 0
    dog,   // 1
    pig,   // 2
    whale, // 3
};

constexpr std::string_view getPetName(Pet pet)
{
    switch (pet)
    {
    case cat:   return "cat";
    case dog:   return "dog";
    case pig:   return "pig";
    case whale: return "whale";
    default:    return "???";
    }
}

constexpr std::optional<Pet> getPetFromString(std::string_view sv)
{
    if (sv == "cat")   return cat;
    if (sv == "dog")   return dog;
    if (sv == "pig")   return pig;
    if (sv == "whale") return whale;

    return {};
}

// pet is an in/out parameter
std::istream& operator>>(std::istream& in, Pet& pet)
{
    std::string s{};
    in >> s; // get input string from user

    std::optional<Pet> match { getPetFromString(s) };
    if (match) // if we found a match
    {
        pet = *match; // dereference std::optional to get matching enumerator
        return in;
    }

    // We didn't find a match, so input must have been invalid
    // so we will set input stream to fail state
    in.setstate(std::ios_base::failbit);
    
    // On an extraction failure, operator>> zero-initializes fundamental types
    // Uncomment the following line to make this operator do the same thing
    // pet = {};

    return in;
}

int main()
{
    std::cout << "Enter a pet: cat, dog, pig, or whale: ";
    Pet pet{};
    std::cin >> pet;
        
    if (std::cin) // if we found a match
        std::cout << "You chose: " << getPetName(pet) << '\n';
    else
    {
        std::cin.clear(); // reset the input stream to good
        std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
        std::cout << "Your pet was not valid\n";
    }

    return 0;
}

There are a few differences from the output case worth noting here. First, std::cin has type std::istream, so we use std::istream& as the type of our left parameter and return value instead of std::ostream&. Second, the pet parameter is a non-const reference. This allows our operator>> to modify the value of the right operand that is passed in if our extraction results in a match.

Inside the function, we use operator>> to input a std::string (something it already knows how to do). If the value the user enters matches one of our pets, then we can assign pet the appropriate enumerator and return the left operand (in).

If the user did not enter a valid pet, then we handle that case by putting std::cin into “failure mode”. This is the state that std::cin typically goes into when an extraction fails. The caller can then check std::cin to see if the extraction succeeded or failed.

#include <iostream>

enum Color
{
    black, // 0
    red,   // 1
    blue,  // 2
};

int main()
{
    Color shirt{ blue };

    std::cout << "Your shirt is " << shirt << '\n';

    return 0;
}

This prints:

Your shirt is 2

Because operator<< doesn’t know how to print a Color, the compiler will implicitly convert Color into an integral value and print that instead.

Most of the time, printing an enumeration as an integral value (such as 2) isn’t what we want. Instead, we typically want to print the name of whatever the enumerator represents (e.g. blue). C++ doesn’t come with an out-of-the-box way to do this, so we’ll have to find a solution ourselves. Fortunately, that’s not very difficult.

Getting the name of an enumerator

The typical way to get the name of an enumerator is to write a function that allows us to pass in an enumerator and returns the enumerator’s name as a string. But that requires some way to determine which string should be returned for a given enumerator.

There are two common ways to do this.

In lesson 8.5 -- Switch statement basics, we noted that a switch statement can switch on either an integral value or an enumerated value. In the following example, we use a switch statement to select an enumerator and return the appropriate color string literal for that enumerator:

#include <iostream>
#include <string_view>

enum Color
{
    black,
    red,
    blue,
};

constexpr std::string_view getColorName(Color color)
{
    switch (color)
    {
    case black: return "black";
    case red:   return "red";
    case blue:  return "blue";
    default:    return "???";
    }
}

int main()
{
    constexpr Color shirt{ blue };

    std::cout << "Your shirt is " << getColorName(shirt) << '\n';

    return 0;
}

This prints:

Your shirt is blue

In the above example, we switch on color, which holds the enumerator we passed in. Inside the switch, we have a case-label for each enumerator of Color. Each case returns the name of the appropriate color as a C-style string literal. This C-style string literal gets implicitly converted into a std::string_view, which is returned to the caller. We also have a default case which returns "???", in case the user passes in something we didn’t expect.

The function is constexpr so that we can use the color’s name in a constant expression.

While this lets us get the name of an enumerator, if we want to print that name to the console, having to do std::cout << getColorName(shirt) isn’t quite as nice as std::cout << shirt. We’ll teach std::cout how to print an enumeration in upcoming lesson 13.5 -- Introduction to overloading the I/O operators.

The second way to solve the program of mapping enumerators to strings is to use an array. We cover this in lesson 17.6 -- std::array and enumerations.

Unscoped enumerator input

Now let’s take a look at an input case. In the following example, we define a Pet enumeration. Because Pet is a program-defined type, the language doesn’t know how to input a Pet using std::cin:

#include <iostream>

enum Pet
{
    cat,   // 0
    dog,   // 1
    pig,   // 2
    whale, // 3
};

int main()
{
    Pet pet { pig };
    std::cin >> pet; // compile error: std::cin doesn't know how to input a Pet

    return 0;
}

One simple way to work around this is to read in an integer, and use static_cast to convert the integer to an enumerator of the appropriate enumerated type:

#include <iostream>
#include <string_view>

enum Pet
{
    cat,   // 0
    dog,   // 1
    pig,   // 2
    whale, // 3
};

constexpr std::string_view getPetName(Pet pet)
{
    switch (pet)
    {
    case cat:   return "cat";
    case dog:   return "dog";
    case pig:   return "pig";
    case whale: return "whale";
    default:    return "???";
    }
}

int main()
{
    std::cout << "Enter a pet (0=cat, 1=dog, 2=pig, 3=whale): ";

    int input{};
    std::cin >> input; // input an integer

    if (input < 0 || input > 3)
        std::cout << "You entered an invalid pet\n";
    else
    {
        Pet pet{ static_cast<Pet>(input) }; // static_cast our integer to a Pet
        std::cout << "You entered: " << getPetName(pet) << '\n';
    }

    return 0;
}

While this works, it’s a bit awkward. Also note that we should only static_cast<Pet>(input) once we know input is in range of the enumerator.

Getting an enumeration from a string

Instead of inputting a number, it would be nicer if the user could type in a string representing an enumerator (e.g. “pig”), and we could convert that string into the appropriate Pet enumerator. However, doing this requires us to solve a couple of challenges.

First, we can’t switch on a string, so we need to use something else to match the string the user passed in. The simplest approach here is to use a series of if-statements.

Second, what Pet enumerator should we return if the user passes in an invalid string? One option would be to add an enumerator to represent “none/invalid”, and return that. However, a better option is to use std::optional here.

#include <iostream>
#include <optional> // for std::optional
#include <string>
#include <string_view>

enum Pet
{
    cat,   // 0
    dog,   // 1
    pig,   // 2
    whale, // 3
};

constexpr std::string_view getPetName(Pet pet)
{
    switch (pet)
    {
    case cat:   return "cat";
    case dog:   return "dog";
    case pig:   return "pig";
    case whale: return "whale";
    default:    return "???";
    }
}

constexpr std::optional<Pet> getPetFromString(std::string_view sv)
{
    // We can only switch on an integral value (or enum), not a string
    // so we have to use if-statements here
    if (sv == "cat")   return cat;
    if (sv == "dog")   return dog;
    if (sv == "pig")   return pig;
    if (sv == "whale") return whale;
    
    return {};
}

int main()
{
    std::cout << "Enter a pet: cat, dog, pig, or whale: ";
    std::string s{};
    std::cin >> s;
        
    std::optional<Pet> pet { getPetFromString(s) };

    if (!pet)
        std::cout << "You entered an invalid pet\n";
    else
        std::cout << "You entered: " << getPetName(*pet) << '\n';

    return 0;
}

In the above solution, we use a series of if-else statements to do string comparisons. If the user’s input string matches an enumerator string, we return the appropriate enumerator. If none of the strings match, we return {}, which means “no value”.

#include <algorithm> // for std::transform
#include <cctype>    // for std::tolower
#include <iterator>  // for std::back_inserter
#include <string>
#include <string_view>

// This function returns a std::string that is the lower-case version of the std::string_view passed in.
// Only 1:1 character mapping can be performed by this function
std::string toASCIILowerCase(std::string_view sv)
{
    std::string lower{};
    std::transform(sv.begin(), sv.end(), std::back_inserter(lower),
        [](char c)
        { 
            return static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
        });
    return lower;
}

Similar to the output case, it would be better if we could just std::cin >> pet. We’ll cover this in upcoming lesson 13.5 -- Introduction to overloading the I/O operators.