Constant expressions

Defines an expression that can be evaluated at compile time.

Such expressions can be used as non-type template arguments, array sizes, and in other contexts that require constant expressions, e.g.

int n = 1;
std::array<int, n> a1; // error: n is not a constant expression
const int cn = 2;
std::array<int, cn> a2; // OK: cn is a constant expression

Core constant expressions

A core constant expression is any expression whose evaluation would not evaluate any one of the following:

1. the this pointer, except in a constexpr function or a constexpr constructor that is being evaluated as part of the expression
2. a function call expression that calls a function (or a constructor) that is not declared constexpr

   constexpr int n = std::numeric_limits<int>::max(); // OK: max() is constexpr
   constexpr int m = std::time(nullptr); // Error: std::time() is not constexpr

3. a function call to a constexpr function which is declared, but not defined
4. a function call to a constexpr function/constructor template instantiation where the instantiation fails to satisfy constexpr function/constructor requirements.
5. an expression that would exceed the implementation-defined limits
6. an expression whose evaluation leads to any form of core language undefined behavior (including signed integer overflow, division by zero, pointer arithmetic outside array bounds, etc). Whether standard library undefined behavior is detected is unspecified.

   constexpr double d1 = 2.0/1.0; // OK
   constexpr double d2 = 2.0/0.0; // Error: not defined
   constexpr int n = std::numeric_limits<int>::max() + 1; // Error: overflow
   int x, y, z[30];
   constexpr auto e1 = &y - &x; // Error: undefined
   constexpr auto e2 = &z[20] - &z[3]; // OK
   constexpr std::bitset<2> a; 
   constexpr bool b = a[2]; // UB, but unspecified if detected

7. (until C++17) a lambda expression
8. an lvalue-to-rvalue implicit conversion, unless the lvalue...
   1. has integral or enumeration type and refers to a complete non-volatile const object, which is initialized with a constant expression

      int main() {
          const std::size_t tabsize = 50;
          int tab[tabsize]; // OK: tabsize is a constant expression
       
          std::size_t n = 50;
          const std::size_t sz = n;
          int tab2[sz]; // error: sz is not a constant expression
                        // because sz is not initialized with a constant expression
      }

   2. is a non-volatile glvalue that refers to an element of a string literal
   3. has literal type and refers to a non-volatile object defined with constexpr or a template parameter object (since C++20) or to its non-mutable subobject
   4. has literal type and refers to a non-volatile object whose lifetime began within the evaluation of this expression
9. an lvalue-to-rvalue implicit conversion or modification applied to a non-active member of a union or its subobject (even if it shares a common initial sequence with the active member)
10. an invocation of an implicitly-defined copy/move constructor or copy/move assignment operator for a union whose active member (if any) is mutable, unless the lifetime of the union object began within the evaluation of this expression
11. (since C++17) (until C++20) an assignment expression or invocation of an overloaded assignment operator that would change the active member of a union
12. an id-expression referring to a variable or a data member of reference type, unless it was initialized with a constant expression or its lifetime began within the evaluation of this expression
13. (since C++20) a checked contract whose predicate evaluates to false
14. conversion from cv void* to any pointer-to-object type
15. (until C++20)dynamic_cast
16. reinterpret_cast
17. pseudo-destructor call
18. (until C++14) an increment or a decrement operator

19. (since C++14) modification of an object, unless the object has non-volatile literal type and its lifetime began within the evaluation of the expression.

    constexpr int incr(int& n) {
      return ++n;
    }
    constexpr int g(int k) {
      constexpr int x = incr(k); // error: incr(k) is not a core constant
                                 // expression because lifetime of k
                                 // began outside the expression incr(k)
      return x;
    }
    constexpr int h(int k) {
      int x = incr(k); // OK: x is not required to be initialized with a core
                       // constant expression
      return x;
    }
    constexpr int y = h(1); // OK: initializes y with the value 2
                            // h(1) is a core constant expression because
                            // the lifetime of k begins inside the expression h(1)

20. (until C++20) a typeid expression applied to a glvalue of polymorphic type
21. a new-expression or a delete-expression
22. (since C++20) a three-way comparison when the result is unspecified
23. an equality or relational operator when the result is unspecified
24. (until C++14) an assignment or a compound assignment operator
25. a throw expression
26. (since C++20) a dynamic_cast or typeid expression that would throw an exception
27. inside a lambda-expression, a reference to this or to a variable defined outside that lambda, if that reference would be an odr-use

    void g() {
      const int n=0;
      constexpr int j=*&n; // OK: outside of a lambda-expression
      [=]{ constexpr int i=n;  // OK: 'n' is not odr-used and not captured here.
           constexpr int j=*&n;// Ill-formed: '&n' would be an odr-use of 'n'.
         };
    }

    note that if the ODR-use takes place in a function call to a closure, it does not refer to this or to an enclosing variable, since it accesses a closure's data member instead. // OK: 'v' & 'm' are odr-used but do not occur in a constant-expression // within the nested lambda auto monad = [](auto v){return [=]{return v;};}; auto bind = [](auto m){return [=](auto fvm){return fvm(m());};}; // OK to have captures to automatic objects created during constant expression evaluation. static_assert(bind(monad(2))(monad)() == monad(2)());

    (since C++17)

Note: Just being a core constant expression does not have any direct semantic meaning: an expression has to be one of the following subsets to be used in certain contexts:

Integral constant expression

Integral constant expression is an expression of integral or unscoped enumeration type implicitly converted to a prvalue, where the converted expression is a core constant expression. If an expression of class type is used where an integral constant expression is expected, the expression is contextually implicitly converted to an integral or unscoped enumeration type.

The following contexts require an integral constant expression:

• bit-field lengths
• enumeration initializers when the underlying type is not fixed

• alignments.

Converted constant expression

A converted constant expression of type T is an expression implicitly converted to type T, where the converted expression is a constant expression, and the implicit conversion sequence contains only:

• constexpr user-defined conversions (so a class can be used where integral type is expected)
• lvalue-to-rvalue conversions
• integral promotions
• non-narrowing integral conversions

• And if any reference binding takes place, it is direct binding (not one that constructs a temporary object)

The following contexts require a converted constant expression:

• case expressions
• enumerator initializers when the underlying type is fixed

• integral and enumeration (until C++17)non-type template arguments.

A contextually converted constant expression of type bool is an expression, contextually converted to bool, where the converted expression is a constant expression and the conversion sequence contains only the conversions above.

The following contexts require a contextually converted constant expression of type bool:

• noexcept specifications
• static assert declarations

Constant expression

void test() {
    static const int a = std::random_device{}();
    constexpr const int& ra = a; // OK: a is a glvalue constant expression
    constexpr int ia = a; // Error: a is not a prvalue constant expression
 
    const int b = 42;
    constexpr const int& rb = b; // Error: b is not a glvalue constant expression
    constexpr int ib = b; // OK: b is a prvalue constant expression
}

Notes

Defect reports

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

See also