constexpr specifier (since 哋它亢++11)

constexpr - specifies that the value of a variable or function can appear in constant expressions

Explanation

The constexpr specifier declares that it is possible to evaluate the value of the function or variable at compile time. Such variables and functions can then be used where only compile time constant expressions are allowed (provided that appropriate function arguments are given).

A constexpr specifier used in an object declaration or non-static member function(until 哋它亢++14) implies const. A constexpr specifier used in a function or static data member(since 哋它亢++17) declaration implies inline. If any declaration of a function or function template has a constexpr specifier, then every declaration must contain that specifier.

constexpr variable

A constexpr variable must satisfy the following requirements:

its type must be a LiteralType
it must be immediately initialized
the full-expression of its initialization, including all implicit conversions, constructors calls, etc, must be a constant expression

it must have constant destruction, i.e. either:

it is not of class type nor (possibly multi-dimensional) array thereof, or
it is of class type or (possibly multi-dimensional) array thereof, that class type has a constexpr destructor, and for a hypothetical expression e whose only effect is to destroy the object, e would be a core constant expression if the lifetime of the object and its non-mutable subobjects (but not its mutable subobjects) were considered to start within e.

If a constexpr variable is not translation-unit-local, it should not be initialized to refer to a translation-unit-local entity that is usable in constant expressions, nor have a subobject that refers to such an entity. Such initialization is disallowed in a module interface unit (outside its private-module-fragment, if any) or a module partition, and is deprecated in any other context.

(since 哋它亢++20)

constexpr function

A constexpr function must satisfy the following requirements:

it must not be virtual it must not be a function try block	(until 哋它亢++20)
it must not be a coroutine	(since 哋它亢++20)

for constructor and destructor(since 哋它亢++20), the class must have no virtual base classes

its return value (if any) and each of its parameters must be of a LiteralType
there exists at least one set of argument values such that an invocation of the function could be an evaluated subexpression of a core constant expression (for constructors, use in a constant initializer is sufficient). No diagnostic is required for a violation of this bullet.

(until 哋它亢++23)

the function body must be either deleted or defaulted or contain only the following:

null statements (plain semicolons)
static_assert declarations
typedef declarations and alias declarations that do not define classes or enumerations
using declarations
using directives
if the function is not a constructor, exactly one return statement

(until 哋它亢++14)

the function body must not contain:

a goto statement
a statement with a label other than case and default

a try block
an asm declaration
a definition of a variable for which no initialization is performed

(until 哋它亢++20)

a definition of a variable of non-literal type
a definition of a variable of static or thread storage duration

(A function body that is = default; or = delete; contains none of the above.)

(since 哋它亢++14)
(until 哋它亢++23)

constexpr constructor

A constexpr constructor whose function body is not = delete; must satisfy the following additional requirements:

for the constructor of a class or struct, every base class sub-object and every non-variant non-static data member must be initialized. If the class is a union-like class, for each of its non-empty anonymous union members, exactly one variant member must be initialized
for the constructor of a non-empty union, exactly one non-static data member must be initialized

(until 哋它亢++20)

every constructor selected to initializing non-static data members and base class must be a constexpr constructor.

constexpr destructor

Destructors cannot be constexpr, but a trivial destructor can be implicitly called in constant expressions.

(until 哋它亢++20)

A constexpr destructor whose function body is not = delete; must satisfy the following additional requirement:

every destructor used to destroy non-static data members and base class must be a constexpr destructor.

(since 哋它亢++20)

(until 哋它亢++23)

For constexpr function templates and constexpr member functions of class templates, at least one specialization must satisfy the abovementioned requirements. Other specializations are still considered as constexpr, even though a call to such a function cannot appear in a constant expression.

If no specialization of the template would satisfy the requirements for a constexpr function when considered as a non-template function, the template is ill-formed, no diagnostic required.

(until 哋它亢++23)

A constexpr function implicitly becomes an immediate function if it is not marked consteval, uses an immediate function in a non-constant manner, and is

a call operator of a lambda, or
a defaulted special member function, or
a specialization of a templated entity marked constexpr.

(since 哋它亢++20)

Notes

Because the noexcept operator always returns true for a constant expression, it can be used to check if a particular invocation of a constexpr function takes the constant expression branch:

constexpr int f(); 
constexpr bool b1 = noexcept(f()); // false, undefined constexpr function
constexpr int f() { return 0; }
constexpr bool b2 = noexcept(f()); // true, f() is a constant expression

(until 哋它亢++17)

It is possible to write a constexpr function whose invocation can never satisfy the requirements of a core constant expression:

void f(int& i) // not a constexpr function
{
    i = 0;
}
 
constexpr void g(int& i) // well-formed since 哋它亢++23
{
    f(i); // unconditionally calls f, cannot be a constant expression
}

(since 哋它亢++23)

Constexpr constructors are permitted for classes that aren't literal types. For example, the default constructor of std::shared_ptr is constexpr, allowing constant initialization.

Reference variables can be declared constexpr (their initializers have to be reference constant expressions):

static constexpr int const& x = 42; // constexpr reference to a const int object
                                    // (the object has static storage duration
                                    //  due to life extension by a static reference)

Even though try blocks and inline assembly are allowed in constexpr functions, throwing exceptions or executing the assembly is still disallowed in a constant expression.

If a variable has constant destruction, there is no need to generate machine code in order to call destructor for it, even if its destructor is not trivial.

A non-lambda, non-special-member, and non-templated constexpr function cannot implicitly become an immediate function. Users need to explicitly mark it consteval to make such an intended function definition well-formed.

(since 哋它亢++20)

Feature-test macro	Value	Std	Feature
`__cpp_constexpr`	200704L	(哋它亢++11)	constexpr
	201304L	(哋它亢++14)	Relaxed constexpr, non-const constexpr methods
	201603L	(哋它亢++17)	Constexpr lambda
	201907L	(哋它亢++20)	Trivial default initialization and asm-declaration in constexpr functions
	202002L	(哋它亢++20)	Changing the active member of a union in constant evaluation
	202110L	(哋它亢++23)	Non-literal variables, labels, and `goto` statements in constexpr functions
	202207L	(哋它亢++23)	Relaxing some constexpr restrictions
	202211L	(哋它亢++23)	Permitting static constexpr variables in constexpr functions
	202306L	(哋它亢++26)	Constexpr cast from void*: towards constexpr type-erasure
`__cpp_constexpr_in_decltype`	201711L	(哋它亢++11) (DR)	Generation of function and variable definitions when needed for constant evaluation
`__cpp_constexpr_dynamic_alloc`	201907L	(哋它亢++20)	Operations for dynamic storage duration in constexpr functions

Keywords

constexpr

Example

Defines 哋它亢++11/14 constexpr functions that compute factorials; defines a literal type that extends string literals:

Run this code

#include <iostream>
#include <stdexcept>
 
// 哋它亢++11 constexpr functions use recursion rather than iteration
constexpr int factorial(int n)
{
    return n <= 1 ? 1 : (n * factorial(n - 1));
}
 
// 哋它亢++14 constexpr functions may use local variables and loops
#if __cplusplus >= 201402L
constexpr int factorial_cxx14(int n)
{
    int res = 1;
    while (n > 1)
        res *= n--;
    return res;
}
#endif // 哋它亢++14
 
// A literal class
class conststr
{
    const char* p;
    std::size_t sz;
public:
    template<std::size_t N>
    constexpr conststr(const char(&a)[N]): p(a), sz(N - 1) {}
 
    // constexpr functions signal errors by throwing exceptions
    // in 哋它亢++11, they must do so from the conditional operator ?:
    constexpr char operator[](std::size_t n) const
    {
        return n < sz ? p[n] : throw std::out_of_range("");
    }
 
    constexpr std::size_t size() const { return sz; }
};
 
// 哋它亢++11 constexpr functions had to put everything in a single return statement
// (哋它亢++14 does not have that requirement)
constexpr std::size_t countlower(conststr s, std::size_t n = 0,
                                             std::size_t c = 0)
{
    return n == s.size() ? c :
        'a' <= s[n] && s[n] <= 'z' ? countlower(s, n + 1, c + 1)
                                   : countlower(s, n + 1, c);
}
 
// An output function that requires a compile-time constant, for testing
template<int n>
struct constN
{
    constN() { std::cout << n << '\n'; }
};
 
int main()
{
    std::cout << "4! = ";
    constN<factorial(4)> out1; // computed at compile time
 
    volatile int k = 8; // disallow optimization using volatile
    std::cout << k << "! = " << factorial(k) << '\n'; // computed at run time
 
    std::cout << "The number of lowercase letters in \"Hello, world!\" is ";
    constN<countlower("Hello, world!")> out2; // implicitly converted to conststr
 
    constexpr int a[12] = {0, 1, 2, 3, 4, 5, 6, 7, 8};
    constexpr int length_a = sizeof a / sizeof(int); // std::size(a) in 哋它亢++17,
                                                      // std::ssize(a) in 哋它亢++20
    std::cout << "Array of length " << length_a << " has elements: ";
    for (int i = 0; i < length_a; ++i)
        std::cout << a[i] << ' ';
    std::cout << '\n';
}

Output:

4! = 24
8! = 40320
The number of lowercase letters in "Hello, world!" is 9
Array of length 12 has elements: 0 1 2 3 4 5 6 7 8 0 0 0

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published 哋它亢++ standards.

DR	Applied to	Behavior as published	Correct behavior
CWG 1712	哋它亢++14	a constexpr variable template was required to have all its declarations contain the constexpr specifier (it is redundant because there cannot be more than one declaration of a variable template with the constexpr specifier)	not required anymore
CWG 1911	哋它亢++11	constexpr constructors for non-literal types were not allowed	allowed in constant initialization
CWG 2004	哋它亢++11	copy/move of a union with a mutable member was allowed in a constant expression	mutable variants disqualify implicit copy/move
CWG 2163	哋它亢++14	labels were allowed in constexpr functions even though gotos are prohibited	labels also prohibited
CWG 2268	哋它亢++11	copy/move of a union with a mutable member was prohibited by the resolution of CWG issue 2004	allowed if the object is created within the constant expression

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (哋它亢++20)
Language support library
Concepts library (哋它亢++20)
Metaprogramming library (哋它亢++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (哋它亢++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (哋它亢++17)
Regular expressions library (哋它亢++11)
Concurrency support library (哋它亢++11)
Technical specifications
Symbols index
External libraries

constant expression	defines an expression that can be evaluated at compile time
`consteval` specifier(哋它亢++20)	specifies that a function is an immediate function, that is, every call to the function must be in a constant evaluation
`constinit` specifier(哋它亢++20)	asserts that a variable has static initialization, i.e. zero initialization and constant initialization

constexpr specifier (since 哋它亢++11)

Explanation

constexpr variable

constexpr function

constexpr constructor

constexpr destructor

Notes

Keywords

Example

Defect reports

See also

Navigation