constexpr in C++: variables, functions and static constexpr

constexpr in C++ marks a variable or a function whose value can be computed while the program is compiled. A constexpr variable is a constant the compiler must know, so it can size an array. A constexpr function can be run by the compiler when its arguments are constants, and runs like any other function when they are not.

The smallest whole program uses both, for a game of up to four players:

#include <iostream>
#include <iterator>

constexpr int max_players = 4;          // known while compiling

constexpr int square(int x) {
    return x * x;
}

int main(int argc, char*[]) {
    int scores[max_players] = {};       // OK: an array size
    static_assert(square(12) == 144);   // computed by the compiler

    int n = argc + 6;                   // known only while running: 7
    std::cout << "slots: " << std::size(scores) << '\n';
    std::cout << "square(n): " << square(n) << '\n';
}

It printed:

slots: 4
square(n): 49

A static_assert is a check the compiler makes: if it is false, the build stops. This one passed, so square(12) was computed while compiling. square(n) ran at run time, because n comes from argc, the count of command-line arguments, known only once the program starts.

The samples on this page are C++17, and C++20 where a comment says so, built with MSVC 19.44, Clang 19.1 (MSVC STL), GCC 16.2 and Clang 23.1 (libc++); all four agreed on every one shown. Since When lists the compiler releases that added each feature.

What is a constexpr variable?

A constexpr variable is a constant whose value the compiler knows: it must be initialized where it is declared, by an expression the compiler can compute. That is what lets it size an array or be a template argument:

constexpr int max_players = 4;
constexpr int seconds_per_day = 24 * 60 * 60;  // done by the compiler

int scores[max_players];                 // a built-in array's size
std::array<int, max_players> lives{};    // a template argument

static_assert(seconds_per_day == 86400);
static_assert(std::is_const_v<decltype(max_players)>);  // it is const

Initialize one from a value the compiler cannot know, and the build fails:

int n = 5;
constexpr int doubled = n * 2;  // error: n is not a constant

n holds 5, but it is an ordinary variable, not a constant. Clang said constexpr variable 'doubled' must be initialized by a constant expression.

constexpr vs const: what is the difference?

const promises that a value will not change once it is set, and that value may be computed while the program runs; constexpr promises that the compiler knows the value. Every constexpr variable is const ([dcl.constexpr]), but not every const variable is a compile-time constant.

const int limit = read_setting();, where read_setting is an ordinary function, compiles and is fixed from then on, but it is not a compile-time constant. A const int set from a constant, such as const int rows = 3;, is one: the language makes that exception for const integers, and rows sized an array as well as constexpr int cols = 4; did.

Using limit as an array size is not standard C++: MSVC rejected it, Clang accepted it with a warning that calls it an extension, and GCC accepted it without a warning at -Wall -Wextra. constexpr is what guarantees the value is known while compiling.

What const does on pointers, references and member functions is in const in C++.

Is a constexpr function evaluated at compile time?

Yes, when its arguments are constants and the result is needed while compiling: in a constexpr variable, an array size or a static_assert. Called with a value known only while running, it runs like any other C++ function, so one function serves both:

constexpr int factorial(int n) {
    int result = 1;
    for (int i = 2; i <= n; ++i)
        result *= i;
    return result;
}
// ...
static_assert(factorial(5) == 120);   // done by the compiler
int seatings[factorial(4)] = {};      // 24 ways to seat 4 players

int n = argc + 5;                     // known only now: 6
std::cout << "seatings: " << std::size(seatings) << '\n';
std::cout << "factorial(n): " << factorial(n) << '\n';

All four printed seatings: 24 and factorial(n): 720.

Demand a compile-time result from a run-time value, and the build fails:

constexpr int big = factorial(argc);  // error: argc is not known

Clang’s note names the cause: function parameter 'argc' with unknown value cannot be used in a constant expression.

What can a constexpr function contain?

In C++11 the body could hold little more than one return statement. Since C++14 it may declare local variables and use loops, if and switch, as factorial does. C++20 added more, including try blocks, virtual functions and memory from the heap: since then a std::string or a std::vector can be used inside a constexpr function.

What is static constexpr in a class?

A static constexpr data member is a constant that belongs to the class, not to each object, with its value written in the class. constexpr static is the same thing in the other order:

class Board {
public:
    static constexpr int size = 8;         // one for the class
    constexpr static int max_players = 4;  // the same, other order

    char cells[size][size] = {};           // sizes a member array

    int squares() const {
        return size * size;                // used inside the class
    }
};

From outside the class it is Board::size. All four printed sizeof(Board): 64, the 64 cells alone: the constants take no room in an object. Since C++17 a static constexpr member is implicitly inline, so it needs no definition outside the class.

What is inline constexpr in a header?

A constexpr variable outside a class, in a header file, gives every source file that includes it its own copy; inline constexpr, since C++17, makes them all share one object:

inline constexpr int port = 8080;  // one object in the program
constexpr int retries = 3;         // one object per source file

In a program of two source files that compared the addresses they saw, all four printed one port: true and one retries: false. An inline variable can be defined in every file that includes it and still be one object, so write the constants in a header as inline constexpr. A constexpr function needs no inline there: it is implicitly inline, so define it whole in the header.

What are consteval and constinit?

Both are C++20. A consteval function must run in the compiler, and constinit makes sure a global variable gets its value while compiling, but leaves it changeable:

consteval int cube(int x) {            // C++20: only in the compiler
    return x * x * x;
}

constinit int counter = cube(2);       // C++20: set while compiling

int main() {
    constexpr int volume = cube(3);    // a constant argument: OK
    std::cout << "volume: " << volume << '\n';

    counter += 1;                      // constinit is not const
    std::cout << "counter: " << counter << '\n';
}

Built as C++20, all four printed volume: 27 and counter: 9. Called with a run-time n, cube(n) was rejected by all four; GCC said call to consteval function 'cube(n)' is not a constant expression.

const, constexpr, static constexpr or inline constexpr: which should you write?

The rest of the core language is in Language.