[expr.const] (original) (raw)

7 Expressions [expr]

7.7 Constant expressions [expr.const]

Certain contexts require expressions that satisfy additional requirements as detailed in this subclause; other contexts have different semantics depending on whether or not an expression satisfies these requirements.

Expressions that satisfy these requirements, assuming that copy elision is not performed, are calledconstant expressions.

[Note 1:

Constant expressions can be evaluated during translation.

— _end note_]

The constituent values of an object o are

• if o has scalar type, the value of o;
• otherwise, the constituent values of any direct subobjects of oother than inactive union members.

The constituent references of an object o are

• any direct members of o that have reference type, and
• the constituent references of any direct subobjects of oother than inactive union members.

The constituent values and constituent references of a variable x are defined as follows:

• If x declares an object, the constituent values and references of that object are constituent values and references of x.
• If x declares a reference, that reference is a constituent reference of x.

For any constituent reference r of a variable x, if r is bound to a temporary object or subobject thereof whose lifetime is extended to that of r, the constituent values and references of that temporary object are also constituent values and references of x, recursively.

An object o is constexpr-referenceable from a point P if

• o has static storage duration, or
• o has automatic storage duration, and, letting v denote
  • the variable corresponding to o's complete object or
  • the variable to whose lifetime that of o is extended,
    the smallest scope enclosing v and the smallest scope enclosing Pthat are neither
  • block scopes nor
  • function parameter scopes associated with a requirement-parameter-list
    are the same function parameter scope.

[Example 1: struct A { int m;const int& r;};void f() { static int sx;thread_local int tx; int ax; A aa = {1, 2};static A sa = {3, 4};auto lambda = [] { int ay;};} — _end example_]

An object or reference x isconstexpr-representable at a point P if, for each constituent value of x that points to or past an object o, and for each constituent reference of x that refers to an object o,o is constexpr-referenceable from P.

A variable v is constant-initializable if

• the full-expression of its initialization is a constant expression when interpreted as a constant-expressionwith all contract assertions using the ignore evaluation semantic ([basic.contract.eval]),
  [Note 2:
  Within this evaluation,std​::​is_constant_evaluated() ([meta.const.eval]) returns true.
  — end note_]
  [_Note 3:
  The initialization, when evaluated, can still evaluate contract assertions with other evaluation semantics, resulting in a diagnostic or ill-formed program if a contract violation occurs.
  — _end note_]
• immediately after the initializing declaration of v, the object or reference x declared by vis constexpr-representable, and
• if x has static or thread storage duration,x is constexpr-representable at the nearest point whose immediate scope is a namespace scope that follows the initializing declaration of v.

A constant-initializable variable is constant-initializedif either it has an initializer or its type is const-default-constructible ([dcl.init.general]).

[Example 2: void f() { int ax = 0; thread_local int tx = 0; static int sx; static int& rss = sx; static int& rst = tx; static int& rsa = ax; thread_local int& rts = sx; thread_local int& rtt = tx; thread_local int& rta = ax; int& ras = sx; int& rat = tx; int& raa = ax; } — _end example_]

A variable is potentially-constant if it is constexpr or it has reference or non-volatile const-qualified integral or enumeration type.

A constant-initialized potentially-constant variable V isusable in constant expressions at a point P ifV's initializing declaration D is reachable from P and

• V is constexpr,
• V is not initialized to a TU-local value, or
• P is in the same translation unit as D.

An object or reference ispotentially usable in constant expressions at point P if it is

• the object or reference declared by a variable that is usable in constant expressions at P,
• a temporary object of non-volatile const-qualified literal type whose lifetime is extended ([class.temporary]) to that of a variable that is usable in constant expressions at P,
• a template parameter object,
• a string literal object,
• a non-mutable subobject of any of the above, or
• a reference member of any of the above.

An object or reference is usable in constant expressions at point Pif it is an object or reference that is potentially usable in constant expressions at P and is constexpr-representable at P.

[Example 3: struct A { int* const & r;};void f(int x) { constexpr A a = {&x};static_assert(a.r == &x); [&] { static_assert(a.r != nullptr); }();} — _end example_]

An expression E is a core constant expressionunless the evaluation of E, following the rules of the abstract machine ([intro.execution]), would evaluate one of the following:

• this ([expr.prim.this]), except
  • in a constexpr function ([dcl.constexpr]) that is being evaluated as part of E or
  • when appearing as the postfix-expression of an implicit or explicit class member access expression ([expr.ref]);
• a control flow that passes through a declaration of a block variable ([basic.scope.block]) with static ([basic.stc.static]) or thread ([basic.stc.thread]) storage duration, unless that variable is usable in constant expressions;
  [Example 4: constexpr char test() { static const int x = 5;static constexpr char c[] = "Hello World";return *(c + x);} static_assert(' ' == test()); — _end example_]
• an invocation of a non-constexpr function;67
• an invocation of an undefined constexpr function;
• an invocation of an instantiated constexpr function that is not constexpr-suitable;
• an invocation of a virtual function ([class.virtual]) for an object whose dynamic type is constexpr-unknown;
• an expression that would exceed the implementation-defined limits (see [implimits]);
• an operation that would have undefined or erroneous behavior as specified in [intro] through [cpp];68
• an lvalue-to-rvalue conversion unless it is applied to
  • a glvalue of type cv std​::​nullptr_t,
  • a non-volatile glvalue that refers to an object that is usable in constant expressions, or
  • a non-volatile glvalue of literal type that refers to a non-volatile object whose lifetime began within the evaluation of E;
• an lvalue-to-rvalue conversion that is applied to a glvalue that refers to a non-active member of a union or a subobject thereof;
• an lvalue-to-rvalue conversion that is applied to an object with an indeterminate value;
• 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 E;
• in a lambda-expression, a reference to this or to a variable with automatic storage duration defined outside thatlambda-expression, where the reference would be an odr-use ([basic.def.odr], [expr.prim.lambda]);
  [Example 5: void g() { const int n = 0;[=] { constexpr int i = n; constexpr int j = *&n; };} — end example_]
  [_Note 4:
  If the odr-use occurs in an invocation of a function call operator of a closure type, it no longer refers to this or to an enclosing variable with automatic storage duration due to the transformation ([expr.prim.lambda.capture]) of the id-expression into an access of the corresponding data member.
  [Example 6: auto monad = [](auto v) { return [=] { return v; }; };auto bind = [](auto m) { return [=](auto fvm) { return fvm(m()); };};static_assert(bind(monad(2))(monad)() == monad(2)()); — _end example_]
  — _end note_]
• a conversion from a prvalue P of type “pointer to cv void” to a type “cv1 pointer to T”, where T is not cv2 void, unless Pis a null pointer value or points to an object whose type is similar to T;
• a reinterpret_cast ([expr.reinterpret.cast]);
• a modification of an object ([expr.assign], [expr.post.incr], [expr.pre.incr]) unless it is applied to a non-volatile lvalue of literal type that refers to a non-volatile object whose lifetime began within the evaluation of E;
• an invocation of a destructor ([class.dtor]) or a function call whose postfix-expression names a pseudo-destructor ([expr.call]), in either case for an object whose lifetime did not begin within the evaluation of E;
• a new-expression ([expr.new]), unless either
  • the selected allocation function is a replaceable global allocation function ([new.delete.single], [new.delete.array]) and the allocated storage is deallocated within the evaluation of E, or
  • the selected allocation function is a non-allocating form ([new.delete.placement]) with an allocated type T, where
    * the placement argument to the new-expression points to an object whose type is similar to T ([conv.qual]) or, if T is an array type, to the first element of an object of a type similar to T, and
    * the placement argument points to storage whose duration began within the evaluation of E;
• a delete-expression ([expr.delete]), unless it deallocates a region of storage allocated within the evaluation of E;
• a call to an instance ofstd​::​allocator<T>​::​allocate ([allocator.members]), unless the allocated storage is deallocated within the evaluation of E;
• a call to an instance ofstd​::​allocator<T>​::​deallocate ([allocator.members]), unless it deallocates a region of storage allocated within the evaluation of E;
• a construction of an exception object, unless the exception object and all of its implicit copies created by invocations ofstd​::​current_exception or std​::​rethrow_exception ([propagation]) are destroyed within the evaluation of E;
• an await-expression ([expr.await]);
• a yield-expression ([expr.yield]);
• a three-way comparison ([expr.spaceship]), relational ([expr.rel]), or equality ([expr.eq]) operator where the result is unspecified;
• a dynamic_cast ([expr.dynamic.cast]) ortypeid ([expr.typeid]) expression on a glvalue that refers to an object whose dynamic type is constexpr-unknown;
• a dynamic_cast ([expr.dynamic.cast]) expression,typeid ([expr.typeid]) expression, ornew-expression ([expr.new]) that would throw an exception where no definition of the exception type is reachable;
• an asm-declaration ([dcl.asm]);
• an invocation of the va_arg macro ([cstdarg.syn]);
• a non-constant library call ([defns.nonconst.libcall]); or
• a goto statement ([stmt.goto]).
  [Note 5:
  A goto statement introduced by equivalence ([stmt]) is not in scope.
  For example, a while statement ([stmt.while]) can be executed during constant evaluation.
  — _end note_]

It isimplementation-defined whether E is a core constant expression if E satisfies the constraints of a core constant expression, but evaluation of E has runtime-undefined behavior.

It is unspecified whether E is a core constant expression if E satisfies the constraints of a core constant expression, but evaluation of E would evaluate

• an operation that has undefined behavior as specified in [library] through [exec] or
• an invocation of the va_start macro ([cstdarg.syn]).

[Example 7: int x; struct A { constexpr A(bool b) : m(b?42:x) { } int m;};constexpr int v = A(true).m; constexpr int w = A(false).m; constexpr int f1(int k) { constexpr int x = k; return x;} constexpr int f2(int k) { int x = k; return x;} constexpr int incr(int &n) { return ++n;} constexpr int g(int k) { constexpr int x = incr(k); return x;} constexpr int h(int k) { int x = incr(k); return x;} constexpr int y = h(1); — _end example_]

For the purposes of determining whether an expression E is a core constant expression, the evaluation of the body of a member function of std​::​allocator<T>as defined in [allocator.members], where T is a literal type, is ignored.

For the purposes of determining whether E is a core constant expression, the evaluation of a call to a trivial copy/move constructor or copy/move assignment operator of a union is considered to copy/move the active member of the union, if any.

[Note 6:

The copy/move of the active member is trivial.

— _end note_]

For the purposes of determining whether E is a core constant expression, the evaluation of an id-expressionthat names a structured binding v ([dcl.struct.bind]) has the following semantics:

• If v is an lvalue referring to the object bound to an invented reference r, the behavior is as if r were nominated.
• Otherwise, if v names an array element or class member, the behavior is that of evaluating e[i] or e.m, respectively, where e is the name of the variable initialized from the initializer of the structured binding declaration, andi is the index of the element referred to by v orm is the name of the member referred to by v, respectively.

[Example 8: #include <tuple> struct S { mutable int m;constexpr S(int m): m(m) {} virtual int g() const;};void f(std::tuple<S&> t) { auto [r] = t;static_assert(r.g() >= 0); constexpr auto [m] = S(1);static_assert(m == 1); using A = int[2];constexpr auto [v0, v1] = A{2, 3};static_assert(v0 + v1 == 5); } — _end example_]

During the evaluation of an expression E as a core constant expression, all id-expressions and uses of *thisthat refer to an object or reference whose lifetime did not begin with the evaluation of Eare treated as referring to a specific instance of that object or reference whose lifetime and that of all subobjects (including all union members) includes the entire constant evaluation.

For such an object that is not usable in constant expressions, the dynamic type of the object is constexpr-unknown.

For such a reference that is not usable in constant expressions, the reference is treated as binding to an unspecified object of the referenced type whose lifetime and that of all subobjects includes the entire constant evaluation and whose dynamic type is constexpr-unknown.

[Example 9: template <typename T, size_t N> constexpr size_t array_size(T (&)[N]) { return N;} void use_array(int const (&gold_medal_mel)[2]) { constexpr auto gold = array_size(gold_medal_mel); } constexpr auto olympic_mile() { const int ledecky = 1500;return []{ return ledecky; };} static_assert(olympic_mile()() == 1500); struct Swim { constexpr int phelps() { return 28; } virtual constexpr int lochte() { return 12; } int coughlin = 12;};constexpr int how_many(Swim& swam) { Swim* p = &swam;return (p + 1 - 1)->phelps();} void splash(Swim& swam) { static_assert(swam.phelps() == 28); static_assert((&swam)->phelps() == 28); Swim* pswam = &swam;static_assert(pswam->phelps() == 28); static_assert(how_many(swam) == 28); static_assert(Swim().lochte() == 12); static_assert(swam.lochte() == 12); static_assert(swam.coughlin == 12); } extern Swim dc;extern Swim& trident;constexpr auto& sandeno = typeid(dc); constexpr auto& gallagher = typeid(trident); — _end example_]

An object a is said to have constant destruction if

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

An integral constant expressionis an expression of integral or unscoped enumeration type, implicitly converted to a prvalue, where the converted expression is a core constant expression.

[Note 7:

Such expressions can be used as bit-field lengths ([class.bit]), as enumerator initializers if the underlying type is not fixed ([dcl.enum]), and as alignments.

— _end note_]

If an expression of literal class type is used in a context where an integral constant expression is required, then that expression is contextually implicitly converted ([conv]) to an integral or unscoped enumeration type and the selected conversion function shall be constexpr.

[Example 10: struct A { constexpr A(int i) : val(i) { } constexpr operator int() const { return val; } constexpr operator long() const { return 42; } private: int val;};constexpr A a = alignof(int);alignas(a) int n; struct B { int n : a; }; — _end example_]

A converted constant expressionof 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

• user-defined conversions,
• lvalue-to-rvalue conversions ([conv.lval]),
• array-to-pointer conversions ([conv.array]),
• function-to-pointer conversions ([conv.func]),
• qualification conversions ([conv.qual]),
• integral promotions ([conv.prom]),
• integral conversions ([conv.integral]) other than narrowing conversions ([dcl.init.list]),
• floating-point promotions ([conv.fpprom]),
• floating-point conversions ([conv.double]) where the source value can be represented exactly in the destination type,
• null pointer conversions ([conv.ptr]) from std​::​nullptr_t,
• null member pointer conversions ([conv.mem]) from std​::​nullptr_t, and
• function pointer conversions ([conv.fctptr]),

and where the reference binding (if any) binds directly.

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

A constant expression is either a glvalue core constant expression that refers to an object or a non-immediate function, or a prvalue core constant expression whose result object ([basic.lval]) satisfies the following constraints:

• each constituent reference refers to an object or a non-immediate function,
• no constituent value of scalar type is an indeterminate or erroneous value ([basic.indet]),
• no constituent value of pointer type is a pointer to an immediate function or an invalid pointer value ([basic.compound]), and
• no constituent value of pointer-to-member type designates an immediate function.

[Note 9:

A glvalue core constant expression that either refers to or points to an unspecified object is not a constant expression.

— _end note_]

[Example 11: consteval int f() { return 42; } consteval auto g() { return f; } consteval int h(int (*p)() = g()) { return p(); } constexpr int r = h(); constexpr auto e = g(); struct S { int x;constexpr S() {} };int i() { constexpr S s; } — _end example_]

Recommended practice: Implementations should provide consistent results of floating-point evaluations, irrespective of whether the evaluation is performed during translation or during program execution.

[Note 10:

Since this document imposes no restrictions on the accuracy of floating-point operations, it is unspecified whether the evaluation of a floating-point expression during translation yields the same result as the evaluation of the same expression (or the same operations on the same values) during program execution.

[Example 12: bool f() { char array[1 + int(1 + 0.2 - 0.1 - 0.1)]; int size = 1 + int(1 + 0.2 - 0.1 - 0.1); return sizeof(array) == size;}

It is unspecified whether the value of f() will be true or false.

— _end example_]

— _end note_]

An expression or conversion is in an immediate function contextif it is potentially evaluated and either:

• its innermost enclosing non-block scope is a function parameter scope of an immediate function,
• it is a subexpression of a manifestly constant-evaluated expression or conversion, or
• its enclosing statement is enclosed ([stmt.pre]) by the compound-statement of a consteval if statement ([stmt.if]).

An invocation is an immediate invocationif it is a potentially-evaluated explicit or implicit invocation of an immediate function and is not in an immediate function context.

An aggregate initialization is an immediate invocation if it evaluates a default member initializer that has a subexpression that is an immediate-escalating expression.

An expression or conversion is immediate-escalatingif it is not initially in an immediate function context and it is either

• a potentially-evaluated id-expressionthat denotes an immediate function that is not a subexpression of an immediate invocation, or
• an immediate invocation that is not a constant expression and is not a subexpression of an immediate invocation.

An immediate-escalating function is

• the call operator of a lambda that is not declared with the consteval specifier,
• a defaulted special member function that is not declared with the consteval specifier, or
• a function that results from the instantiation of a templated entity defined with the constexpr specifier.

An immediate-escalating expression shall appear only in an immediate-escalating function.

An immediate function is a function or constructor that is

• declared with the consteval specifier, or
• an immediate-escalating function _F_whose function body contains an immediate-escalating expression _E_such that E's innermost enclosing non-block scope is F's function parameter scope.

[Example 13: consteval int id(int i) { return i; } constexpr char id(char c) { return c; } template<class T> constexpr int f(T t) { return t + id(t);} auto a = &f<char>; auto b = &f<int>; static_assert(f(3) == 6); template<class T> constexpr int g(T t) { return t + id(42); } template<class T, class F> constexpr bool is_not(T t, F f) { return not f(t);} consteval bool is_even(int i) { return i % 2 == 0; } static_assert(is_not(5, is_even)); int x = 0;template<class T> constexpr T h(T t = id(x)) { return t;} template<class T> constexpr T hh() { return h<T>(); } int i = hh<int>(); struct A { int x;int y = id(x);};template<class T> constexpr int k(int) { return A(42).y; } constexpr int l(int c) pre(c >= 2) { return (c % 2 == 0) ? c / 0 : c;} const int i0 = l(0); const int i1 = l(1); const int i2 = l(2); const int i3 = l(3); — _end example_]

An expression or conversion is manifestly constant-evaluatedif it is:

• a constant-expression, or
• the condition of a constexpr if statement ([stmt.if]), or
• an immediate invocation, or
• the result of substitution into an atomic constraint expression to determine whether it is satisfied ([temp.constr.atomic]), or
• the initializer of a variable that is usable in constant expressions or has constant initialization ([basic.start.static]).69
  [Example 14: template<bool> struct X {}; Xstd::is\_constant\_evaluated()\ x; int y;const int a = std::is_constant_evaluated() ? y : 1; double z[a]; const int b = std::is_constant_evaluated() ? 2 : y; int c = y + (std::is_constant_evaluated() ? 2 : y); constexpr int f() { const int n = std::is_constant_evaluated() ? 13 : 17; int m = std::is_constant_evaluated() ? 13 : 17; char arr[n] = {}; return m + sizeof(arr);} int p = f(); int q = p + f(); — _end example_]

A function or variable isneeded for constant evaluationif it is:

• a constexpr function thatis named byan expression that is potentially constant evaluated, or
• a potentially-constant variable named by a potentially constant evaluated expression.